(fix): polling loop exits on HTTP client timeout, not only on context cancel

(fix): HTTP client timeout too close to poll timeout

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

.gitea/workflows/go-lint.yaml

@@ -0,0 +1,28 @@
+name: Golang lint
+run-name: Linting code
+on: [push, pull_request]
+
+jobs:
+  lint:
+    runs-on: go-latest
+    steps:
+      - name: Checkout repository code
+        uses: actions/checkout@v6
+
+      - name: Verify formatting
+        run: |
+          files="$(gofmt -l .)"
+          if [ -n "$files" ]; then
+            echo "These files are not gofmt-formatted:"
+            echo "$files"
+            exit 1
+          fi
+
+      - name: Run go test
+        run: go test ./...
+
+      - name: Run go vet
+        run: go vet ./...
+
+      - name: Run golangci-lint
+        run: golangci-lint run

.gitignore

@@ -1,2 +1,8 @@
 .idea/
+.wiki/
+.vscode/
 test/
+.codex/
+.codex
+.agents/
+.claude/

.golangci.yml

@@ -5,7 +5,6 @@ linters:
   disable-all: true
   enable:
     - errcheck
-    - govet
     - ineffassign
     - staticcheck
     - unused

AGENTS.md

@@ -1,7 +1,7 @@
 # AGENTS.md
 
 ## Purpose
-This repository uses Codex for full-project Go code review, not diff-only review.
+This repository uses AI coding agents for full-project Go code review, not diff-only review.
 
 When asked to review code, inspect the entire repository and use repository-wide context. Do not limit analysis to the latest commit, pull request diff, or recently changed files.
 
@@ -22,6 +22,20 @@ Review the codebase with focus on:
 - When feasible, make small, high-confidence improvements directly.
 - When uncertain, state confidence level and evidence.
 
+## Documentation languages
+- When creating or expanding project documentation, generate and maintain both English and Russian versions in the same turn whenever reasonably possible.
+- For wiki pages, prefer paired pages such as `Page.md` and `Page-RU.md`.
+- Keep English and Russian pages aligned in structure, major examples, and user-facing guidance.
+- If only one language can be updated safely in the current turn, explicitly say which language is lagging and why.
+
+## Wiki and backlog workflow
+- Treat the wiki as the primary place for large design ideas, architectural drafts, and framework backlog notes.
+- If the agent identifies a substantial new concept or design direction, such as scenes, callback agents, a webhook model, or another framework-level abstraction, the agent must ask the user whether it should also formalize that idea as a draft wiki page.
+- When the user agrees, prefer paired wiki pages such as `Page.md` and `Page-RU.md`, and clearly mark draft design pages with `DRAFT` when the API is not implemented or not yet stable.
+- Keep `TODO.md`, the wiki backlog pages, and `CHANGELOG.md` aligned when framework-level items move between planned and completed states in the main repository.
+- Wiki-only edits must never be added to `CHANGELOG.md`.
+- `AGENTS.md`-only edits must never be added to `CHANGELOG.md`.
+
 ## Go review expectations
 Check for:
 - bugs, fragile logic, invalid assumptions, nil handling issues, resource leaks;
@@ -76,6 +90,58 @@ Before finalizing changes, run the relevant project checks when available:
 
 Prefer the repository’s documented commands. If multiple choices exist, use the most standard and least destructive ones first.
 
+## Versioning and changelog
+- After every code or documentation change in the main repository, update `CHANGELOG.md`.
+- Changes made only inside the `.wiki/` repository must not be added to `CHANGELOG.md`.
+- Changes made only in `AGENTS.md` must not be added to `CHANGELOG.md`.
+- Add changes only to the section for the next version after the latest published git tag.
+- The agent must check the latest published tag, `CHANGELOG.md`, and `utils/version.go` before editing the changelog.
+- Before editing `CHANGELOG.md`, the agent must inspect the full diff between the latest published tag and the current worktree, for example `git diff --name-status <latest-tag> -- .` and targeted `git diff <latest-tag> -- <files>`.
+- Changelog entries must be based on all user-visible changes present between the latest published tag and the current files, including earlier uncommitted or pre-existing worktree changes, not only changes made in the current turn.
+- The agent must not add changelog entries for changes that are not present in the diff from the latest published tag, and must remove or rewrite stale entries that no longer match that diff.
+- The agent must verify that the target changelog version matches the version declared in `utils/version.go`.
+- If the latest published tag is, for example, `v1.0.0`, and `CHANGELOG.md` does not yet contain the next version section, the agent must stop and ask the user which version the change belongs to:
+  1. `v1.0.1`
+  2. `v1.1.0`
+  3. `v2.0.0`
+- The agent must not guess the next version when that section is missing.
+- If the user-selected version does not match `utils/version.go`, the agent must warn about the mismatch and require the version file to be updated before proceeding.
+- Changelog entries must describe all user-visible behavior changes in the diff from the latest published tag, including API additions, fixes, behavior changes, and breaking changes.
+- When a framework backlog item recorded in `TODO.md` is completed, the agent must also update the backlog status using the existing format:
+  1. move the completed item into the top of the `Done` section;
+  2. replace the numbered backlog label with a version tag, for example `1. Scene Model` becomes `[v2.0.0] Scene Model`;
+  3. keep the item title and descriptive notes aligned with the corresponding `CHANGELOG.md` entry.
+- The agent must treat `TODO.md` and `CHANGELOG.md` as linked records: a completed backlog item should not be left in one file as done and in the other as still pending or undocumented.
+
+## Breaking changes policy
+- The agent must detect potential breaking changes before editing public APIs.
+- Breaking changes are forbidden unless the selected target version is a new major version.
+- If the requested change is breaking and the user did not bump the major version, the agent must stop and warn that the change is not allowed under the current version.
+- In that case, the agent must offer only these options:
+  1. do not make the breaking change;
+  2. introduce a backward-compatible alternative such as a new method, function, type, or struct, but only if that keeps the codebase reasonably small and clear;
+  3. bump the major version and then apply the breaking change.
+- Prefer additive compatibility over signature changes when the additive option is small and maintainable.
+- Example: if a method like `ctx.answer(...)` needs an extra parameter, the agent must either require a major-version bump or add a new method that keeps the old method working.
+
+## Commit message format
+- When the user asks for a commit message, the agent must produce it in this format:
+  1. one to four short lines;
+  2. each line must use the format `(<kind>): <text>`;
+  3. `<kind>` must be a short change type such as `fix`, `new`, `tests`, `doc`, `refactor`, or `ci/cd`;
+  4. `<text>` must be a concise 1-5 word description of the change or function;
+  5. each line must start on its own new line;
+  6. when multiple lines are present, kinds must be ordered from top to bottom by this priority: `new`, `fix`, `refactor`, `ci/cd`, `tests`, `doc`.
+- The agent must output the commit message as a plain multiline block that the user can copy directly.
+- Do not collapse the lines into a paragraph, bullet list, or wrapped prose explanation.
+- Keep commit text concise and high-signal.
+- Do not turn commit messages into changelogs.
+
+## Commit signing
+- All commits created by the agent must be GPG-signed.
+- If commit signing or pushing requires leaving the sandbox, the agent must request escalation explicitly before running the command.
+- If a signed commit cannot be created successfully, the agent must report the failure clearly and stop instead of creating an unsigned fallback commit.
+
 ## Output format
 For repo-wide review tasks, structure the result as:
 

CHANGELOG.md

@@ -1,5 +1,286 @@
 # Changelog
 
+## v1.0.2
+
+### Fixed
+- Fixed long-polling stopping permanently when the HTTP client's internal timeout fired. The polling loop was checking `errors.Is(err, context.DeadlineExceeded)`, which matched HTTP client timeout errors (`*url.Error` wraps `context.DeadlineExceeded`), causing the goroutine to exit as if the bot context was canceled. The check is now `ctx.Err() != nil` so only a real context cancellation stops polling.
+- Fixed the HTTP client timeout (45 s) being too close to the long-poll `getUpdates` timeout (30 s default), leaving insufficient margin for connection setup and response transfer. The client timeout is now derived from the configured `PollTimeout` plus a 60-second buffer.
+
+## v1.0.1
+
+### Fixed
+- Fixed webhook always accepting unauthenticated requests when `SecretToken` is not configured. A cryptographically random 32-byte token is now generated automatically when `SecretToken` is empty, so the webhook endpoint is always authenticated. The generated token is logged as a warning so the operator can record it.
+- Fixed `tgapi.NewAPI` and `tgapi.NewUploader` not installing token redaction on their managed loggers. The bot token is now masked as `<TOKEN>` in debug output even when the `tgapi` package is used standalone without the `laniakea.Bot` wrapper.
+
+## v1.0.0
+
+### Breaking Changes
+- Renamed `MsgContext` to `MessageContext` across the public API, including handler signatures (`CommandExecutor`, `MiddlewareExecutor`, scene handler types), all reply/edit/scene helpers, embedded fields on `SceneContext`, and documentation.
+- Removed the `NewPayload(...)` constructor. `NewCommand(...)` builds the underlying `Command[T]` for both `/-`commands and callback payloads; registration via `Plugin.AddPayload`/`Plugin.Payload` decides routing.
+- `MessageContext.Error(...)` no longer sends unclassified errors to the user. Only errors marked with `AsUserError(...)` are surfaced through the centralized reply path; everything else stays internal-only and is logged.
+- `Plugin.Close()` no longer closes a logger supplied through `Plugin.SetLogger(...)`. Only loggers created by the bot during `AddPlugins` registration are owned and closed; caller-supplied loggers remain the caller's responsibility.
+- Renamed final public APIs to idiomatic names before the stable release: `RunWebhookWithContext(...)`, `RunWebhook(...)`, `CloseWebhook()`, `BotWebhookOpts`, `NewBotWebhookOpts()`, `SetWebhookLogger(...)`, and `GetWebhookLogger()`.
+- Renamed plugin builder helpers from `NewCommand(...)` and `NewScene(...)` to `Command(...)` and `Scene(...)`; the surviving `NewCommand(...)` takes the command string before the executor.
+- Renamed command argument value constants to `CommandValueString`, `CommandValueInt`, `CommandValueBool`, and `CommandValueAny`; `NewCommandArg(...)` now defaults to unvalidated `CommandValueAny`.
+- Renamed runner builders from `Onetime(...)` and `Timeout(...)` to `Every(...)` and `Async(...)`; `Runner.Once()` is removed. Use the default configuration (every=0, async=true) for a fire-and-forget goroutine, or `Async(false)` for a synchronous blocking one-shot.
+- Renamed remaining public acronym/casing outliers including `AnswerCallback...`, `ParseMarkdownV2`, `ParseMarkdown`, `GetChatMemberCount`, `DropRateLimitOverflow`, `SetDropRateLimitOverflow`, and inline keyboard builder APIs.
+- Renamed `Observer` event delivery methods `OnReceiveUpdate` → `OnUpdateReceived` and `OnHandledUpdate` → `OnUpdateHandled` to match the `UpdateReceivedEvent`/`UpdateHandledEvent` names and the `OnX` pattern of all other observer methods.
+- `Scene.PluginName` is now unexported; it is assigned by the framework during plugin registration and must not be set by callers.
+- `SceneSession.Data` is now unexported; use the `Set`/`Get`/`HasData`/`ClearData`/`BindData`/`SaveData` helpers instead.
+- `BotPayloadType*` sentinels are now `const` instead of `var`; code that assigned to them will no longer compile.
+
+### Bot API 10.0
+- Added full support for Telegram Bot API 10.0 types, methods, and update kinds.
+
+### Added
+- Added `MessageContext.IsCallback()` and `MessageContext.HasPhoto()` helpers for callback-aware handler code.
+- Added `MessageContext.UpsertKeyboard(...)` and `MessageContext.UpsertKeyboardMarkdown(...)` helpers that edit callback messages, replace photo callback messages with a fresh chat message, and send a new chat message outside callback flow.
+- Added `CommandGroup`, `NewCommandGroup(...)`, `Plugin.CommandGroup(...)`, and `Plugin.AddCommandGroup(...)` helpers for registering prefixed command groups with shared middleware.
+- Added the `tgfmt` package with typed MarkdownV2, HTML, legacy Markdown formatting helpers, and a message entity builder.
+- Added `InlineKeyboardButtonBuilder.SetPayloadType(...)`, `InlineKeyboardButtonBuilder.SetCallbackData(...)`, and `MessageContext.NewInlineKeyboardButton(...)` helpers for payload-aware button building.
+- Added compact callback payload encoding through `BotPayloadCompact`, `BotPayloadCompactBase64`, compact inline keyboard builders, and matching `CallbackData` helpers.
+- Added `BotOpts.PollTimeout`, `BotOpts.SetPollTimeout(...)`, and the `POLL_TIMEOUT` environment variable to configure the long-polling `getUpdates` timeout (default 30 seconds).
+- Added `RateLimiter.Cleanup(idleThreshold)` to evict per-chat limiter state and expired chat cooldowns; the limiter now tracks per-chat last-seen time so long-running bots can bound memory through a periodic runner.
+- Added cached bot identity (`Bot.userID`) populated at `NewBot` so chat-admin policies and similar lookups reuse it instead of issuing a fresh `GetMe` request.
+- Added `tgapi.ResponseError` so Telegram API error codes, descriptions, and response parameters remain inspectable through returned errors.
+- Added nine exported webhook error sentinels — `ErrSetWebhookFailed`, `ErrBotAPINil`, `ErrBotWebhookOptsEmptyPath`, `ErrBotWebhookOptsPathNoSlash`, `ErrBotWebhookOptsPathHasQueryOrFragment`, `ErrBotWebhookOptsPathCollidesStatus`, `ErrBotWebhookTLSFilesIncomplete`, `ErrBotWebhookTLSFilesTooMany`, and `ErrStatusPathSecretRequired` — replacing the previous inline `errors.New(...)` calls so callers can match webhook startup errors with `errors.Is`.
+- Added `ErrInvalidPayload` for compact payload decoding failures so callers can distinguish malformed payload bytes from other decode errors.
+- Panics inside `Bot.handle` and the polling goroutine now emit an `ErrorEvent` through the observer so instrumentation sees runtime panics in addition to normal handler errors.
+
+### Changed
+- Version metadata now reports the stable `v1.0.0` release instead of `v1.0.0-rc.16`.
+- Compact callback payload encoding now escapes `,`, `|`, and `\` in command and arg bytes so payloads containing those bytes round-trip without ambiguity. Note: the format coalesces "no args" with "single empty arg" — both encode as `cmd|` and decode to nil args.
+- `CallbackData.ToJSON()`, `ToBase64()`, `ToCompact()`, and `ToCompactBase64()` now all return an empty string on serialization failure; the previous `ToJSON()` fallback `{"cmd":""}` has been removed so encoder bugs surface visibly instead of routing to no handler.
+- Bot-level middleware blocks now emit a final `UpdateHandledEvent` with `Handled=false`, keeping observer update lifecycles balanced.
+- Plugin registration now warns when `AddCommand`, `AddPayload`, or `AddScene` overwrites an existing entry with the same name instead of silently replacing it.
+- `BotOpts`, `tgapi.APIOpts`, logger utilities, README, and wiki pages now document the final stable API names and configuration options consistently.
+- CI now checks formatting, tests, vet, and lint on both pushes and pull requests.
+
+### Fixed
+- Fixed the update worker pool returning before in-flight handlers completed. `startUpdateWorkers` now calls `pool.StopAndWait()` so the bot waits for already-submitted tasks before runtime exit.
+- Fixed `RateLimiter.getChatLimiter` upgrading a held read lock to a write lock, which could deadlock under contention. The lookup now releases the read lock before acquiring the write lock and re-checks the map.
+- Fixed `RateLimiter` per-chat limiter and lock maps growing unbounded for the lifetime of long-running bots that serve many distinct chats.
+- Fixed `Draft.Push` mutating `Message` before validating the candidate length, leaving the draft in a half-mutated state when the candidate would exceed Telegram's limit. The candidate is now validated first; on failure the draft remains unchanged.
+- Fixed background runners running one extra iteration after context cancellation when both `ctx.Done()` and the ticker were ready in the same `select`.
+- Fixed `Plugin.Close()` double-closing a logger supplied by the caller through `SetLogger(...)`.
+- Fixed compact callback payload corruption for arguments containing `,` or `|` bytes.
+- Fixed `LoadOptsFromEnv` calling `os.Getenv("MAX_WORKERS")` twice when parsing the worker count.
+- Fixed `sceneRuntime` interface carrying a delegating `buildSceneKey` method that just forwarded to a package-level helper; `MessageContext` scene helpers now call the helper directly.
+- Fixed webhook startup so empty-secret warnings are logged only after the webhook logger is initialized.
+- Fixed webhook startup so a logger configured through `SetWebhookLogger(...)` is preserved.
+- Fixed long-polling 429 handling so `getUpdates` retries use Telegram `retry_after` directly and do not inflate later transient-error backoff.
+- Fixed `BotOptsFileJSON` silently dropping `PollTimeout` on round-trip; the field is now encoded and decoded correctly.
+- Fixed the `tgapi.Uploader` returning an ad-hoc error string on Telegram API failures; it now returns `*tgapi.ResponseError` matching the JSON API client, so `errors.As(err, &respErr)` works consistently for both upload and JSON paths.
+- Fixed webhook secret validation to use `subtle.ConstantTimeCompare` instead of a plain string equality check, removing the timing side-channel.
+- Fixed the `/status` handler returning HTTP 403 for a wrong secret, which disclosed endpoint existence; it now returns 404 uniformly for any unauthenticated request.
+
+### Tests
+- Added regression coverage proving bot-level middleware blocks still complete the observer update lifecycle.
+- Added webhook runtime regression coverage for request enqueue through worker execution of a command handler.
+- Added regression coverage for inline callback keyboard upserts and callback target detection.
+- Added regression coverage for command group prefixing, middleware order, clone behavior, and plugin registration.
+- Added formatting coverage for escaping, composition, link destinations, HTML attributes, and legacy Markdown code blocks.
+- Added regression coverage for context-aware inline keyboard button payload encoding.
+- Added regression coverage for compact and Base64-encoded compact callback payload decoding.
+- Added regression coverage for long-polling `retry_after` handling on Telegram 429 responses.
+- Added regression coverage for compact callback payload round-tripping through `,`, `|`, and `\` separator bytes and a missing-separator decode error.
+- Added regression coverage for `Draft.Push` preserving the existing message when validation rejects the candidate.
+- Added regression coverage for `RateLimiter.Cleanup` evicting idle chat limiters and expired chat locks while leaving active state in place.
+- Updated `MessageContext.Error` tests so unclassified errors stay internal-only and only `AsUserError` reaches the user.
+- Added regression coverage for `BotOptsFileJSON` `PollTimeout` round-trip.
+- Added regression coverage proving the `tgapi.Uploader` surfaces `*tgapi.ResponseError` for Telegram 4xx responses.
+- Added regression coverage proving a panic inside `Bot.handle` emits an `ErrorEvent` through the observer.
+- Added regression coverage for the webhook `/status` endpoint rejecting wrong and same-length-but-different secrets with HTTP 404, and accepting the correct secret.
+- Added table-driven regression coverage for `parseCommand` with `/cmd@botname` stripping, bare commands, commands with arguments, and empty input.
+
+## v1.0.0-rc.16
+
+### Breaking Changes
+- Replaced `git.scuroneko.dev/scuroneko/slog` with `git.scuroneko.dev/scuroneko/sneklog/v2` across public logger APIs, including `AppDataLogger`, logger getters, and custom logger setters.
+- Renamed exported `Json`, `Url`, and `Id` identifiers to idiomatic `JSON`, `URL`, and `ID` spellings, including `BotOpts.APIURL`, `BotOpts.SetAPIURL(...)`, `tgapi.APIOpts.SetAPIURL(...)`, `BotOptsFileJSONCodec`, `BotPayloadJSON`, and related README examples.
+- Made the request logger field internal; use `Bot.SetRequestLogger(...)` and `Bot.GetRequestLogger()` instead of accessing `Bot.RequestLogger` directly.
+
+### Added
+- Added `Bot.UpdatesIter(...)` as an iterator wrapper around a single `Bot.Updates(...)` call, including error delivery through the iterator.
+- Added scene-local callback payload handlers through `Scene.OnPayload(...)`, including observer lifecycle events for scene payload execution.
+- Added configurable logger output through `BotOpts.LogFormat`, `BotOpts.SetLogFormat(...)`, `BotOpts.SetLogFormatter(...)`, `tgapi.APIOpts.SetLogFormat(...)`, and `tgapi.APIOpts.SetLogFormatter(...)`.
+- Added JSON BotOpts file format versioning through `ConfigVersion`, `ErrConfigVersionMismatch`, and `BotOpts.FileConfigVersion`.
+- Added `Bot.SetLogger(...)`, `Bot.SetRequestLogger(...)`, `Bot.SetWebHookLogger(...)`, `Bot.GetRequestLogger()`, and `Bot.GetWebHookLogger()` helpers for explicit logger customization.
+
+### Changed
+- Updated `pond/v2` to `v2.7.1`.
+- `Bot.RunWithContext(...)` now closes an explicitly set request logger when `UseRequestLogger` is false and closes webhook loggers before long-polling startup.
+- Bot loggers now apply the configured token replacer consistently across the main bot logger, request logger, internal API and uploader loggers, webhook logger, app-data logger writers, and auto-managed plugin loggers.
+- JSON `BotOpts` files now write `version`, reject newer unsupported config versions, keep older unversioned files loadable, and preserve the loaded file version in `BotOpts.FileConfigVersion`.
+- `Bot.RunWithContext(...)` treats `context.DeadlineExceeded` like `context.Canceled` and exits polling without retry logging.
+- README and README_RU now use the current `JSON`, `URL`, and `ID` public API names.
+
+### Fixed
+- Fixed the go-lint workflow file to end with a newline.
+
+### Tests
+- Added regression coverage for `Bot.UpdatesIter(...)` error delivery and early iterator stop behavior.
+- Added regression coverage proving `Bot.RunWithContext(...)` preserves polling retry attempts and backoff delays across repeated getUpdates failures.
+- Added regression coverage proving polling startup preserves an enabled request logger.
+- Updated file logger regression coverage for the current `sneklog` text prefix format.
+- Added regression coverage proving token masking still applies after `initLoggers(...)` switches loggers to file-backed writers and that auto-managed plugin loggers inherit token masking.
+- Added regression coverage for JSON config version handling and scene-local payload routing, including observer lifecycle events and callback fallthrough behavior.
+- Updated logger helper tests for the explicit log format and formatter parameters.
+
+## v1.0.0-rc.15
+
+### Changed
+- Added file-based `BotOpts` loading and saving through `LoadBotOptsFile(...)`, `SaveBotOptsFile(...)`, and the `BotOptsFileCodec` API, with built-in JSON support.
+- Added plugin-level message fallback handlers for text messages and channel posts that do not match commands.
+- Added godoc for the exported `BotOpts` file codec and load/save helpers.
+- README, README_RU, and bot-configuration wiki pages now document file-based `BotOpts` loading, built-in JSON support, env placeholder expansion, and custom codec usage including the TOML example.
+- Active scenes now let unmatched slash-commands continue into normal bot command routing instead of also executing the current scene step or scene message fallback.
+
+### Tests
+- Added regression coverage for JSON `BotOpts` file codecs, file load/save helpers, decode failures, and env placeholder expansion.
+- Added regression coverage for plugin message fallback routing, observer lifecycle events, command precedence, and middleware blocking.
+- Added regression coverage proving unmatched slash-commands do not trigger active scene step handlers before normal bot command routing.
+
+## v1.0.0-rc.14
+
+### Bot API 9.6
+
+#### Managed Bots
+- Added the field can_manage_bots to the class User.
+- Added the class KeyboardButtonRequestManagedBot and the field request_managed_bot to the class KeyboardButton.
+- Added the class ManagedBotCreated and the field managed_bot_created to the class Message.
+- Added updates about the creation of managed bots and the change of their token, represented by the class ManagedBotUpdated and the field managed_bot in the class Update.
+- Added the methods getManagedBotToken and replaceManagedBotToken.
+- Added the class PreparedKeyboardButton and the method savePreparedKeyboardButton, allowing bots to request users, chats and managed bots from Mini Apps.
+- Added the method requestChat to the class WebApp.
+- Added support for https://t.me/newbot/{manager_bot_username}/{suggested_bot_username}[?name={suggested_bot_name}] links, allowing bots to request the creation of a managed bot via a link.
+
+### Polls
+- Added support for quizzes with multiple correct answers.
+- Replaced the field correct_option_id with the field correct_option_ids in the class Poll.
+- Replaced the parameter correct_option_id with the parameter correct_option_ids in the method sendPoll.
+- Allowed to pass allows_multiple_answers for quizzes in the method sendPoll.
+- Increased the maximum time for automatic poll closure to 2628000 seconds.
+- Added the field allows_revoting to the class Poll.
+- Added the parameter allows_revoting to the method sendPoll.
+- Added the parameter shuffle_options to the method sendPoll.
+- Added the parameter allow_adding_options to the method sendPoll.
+- Added the parameter hide_results_until_closes to the method sendPoll.
+- Added the fields description and description_entities to the class Poll.
+- Added the parameters description, description_parse_mode, and description_entities to the method sendPoll.
+- Added the field persistent_id to the class PollOption, representing a persistent identifier for the option.
+- Added the field option_persistent_ids to the class PollAnswer.
+- Added the fields added_by_user and added_by_chat to the class PollOption, denoting the user and the chat which added the option.
+- Added the field addition_date to the class PollOption, describing the date when the option was added.
+- Added the class PollOptionAdded and the field poll_option_added to the class Message.
+- Added the class PollOptionDeleted and the field poll_option_deleted to the class Message.
+- Added the field poll_option_id to the class ReplyParameters, allowing bots to reply to a specific poll option.
+- Added the field reply_to_poll_option_id to the class Message.
+- Allowed “date_time” entities in checklist title, checklist task text, TextQuote, ReplyParameters quote, sendGift, and giftPremiumSubscription.
+
+**More info**: https://core.telegram.org/bots/api#april-3-2026
+
+### Breaking Changes
+- Exported `tgapi` request parameter structs were renamed from the `*P` suffix to their method names. Update code such as `tgapi.SendMessageP{...}` to `tgapi.SendMessage{...}`.
+
+### Changed
+- *Support for Bot API 9.6*
+- Added missing godoc for recently introduced Telegram Bot API managed-bot, prepared-button, chat-owner, and video-quality exported declarations.
+- Renamed exported `tgapi` request parameter structs from the `*P` suffix to their method names, for example `SendMessageP` -> `SendMessage` and `SetWebhookP` -> `SetWebhook`.
+- Added missing godoc for the exported observer `Event` marker interface.
+- Webhook execution now shares the bot's queued update-dispatch path with polling, including worker-pool delivery, runner startup, single-use run semantics, and default fallback to bot-level update type filters when webhook-specific filters are not set.
+- Webhook godoc and the English and Russian READMEs now describe the bot-level webhook runtime, its single-use lifecycle, and the main `RunWebHookWithContext(...)` entry points more explicitly.
+- `Bot.Close()` once again releases only local resources and no longer deletes remote webhook registrations implicitly; explicit remote webhook teardown remains opt-in through `CloseWebHook()`.
+- Polling and webhook docs now explicitly state that a deployment must delete its webhook before switching from webhook delivery to long polling.
+- Webhook startup now validates path shape and TLS file count before remote webhook setup, and the shared webhook mux now serves both HTTP and TLS runtime paths consistently.
+- Webhook-related `tgapi` request params now use `int8` for `max_connections`, matching Telegram's `1..100` range and the higher-level webhook options API.
+- Webhook startup now also requires a non-empty `SecretToken` when the optional `/status` endpoint is enabled, preventing anonymous exposure of webhook operational metadata.
+- Webhook debug logging now records update metadata instead of dumping raw request bodies.
+- Package docs, README guidance, and core wiki pages now align with the current public API and runtime model, including `NoData`, `SetAppData(...)`, `SetL10n(...)`, `AddAppDataLoggerWriter(...)`, shared runner startup semantics, and the webhook runtime entry points.
+
+### Tests
+- Added regression coverage for webhook queue delivery, webhook runtime single-use behavior, runner startup in webhook mode, and default webhook `allowed_updates` inheritance from bot-level update type configuration.
+- Added regression coverage proving `Bot.Close()` does not make remote webhook delete requests.
+- Added webhook regression coverage for path validation, TLS file-count validation, oversized-body rejection, status-endpoint secret checks, and invalid TLS startup arguments.
+- Added webhook regression coverage proving `/status` cannot be enabled without a non-empty `SecretToken`.
+- Added regression coverage for Bot API 9.6 poll decoding, `managed_bot` update decoding, and structured `setChatMenuButton(...)` request serialization.
+- Added regression coverage for `MaybeInaccessibleMessage` accessible and inaccessible JSON decoding.
+
+## v1.0.0-rc.13
+
+### Added
+- `AsUserError(...)`, `AsInternalError(...)`, `IsUserError(...)`, and `IsInternalError(...)` for explicitly marking centralized handler errors as user-visible or internal-only without breaking the existing default error flow.
+- `Policy[T]`, `RequirePolicy(...)`, and built-in chat and callback policy helpers for expressing reusable authorization rules through the existing middleware pipeline.
+- `Bot.UsePolicy(...)` and `Plugin.UsePolicy(...)` as shorthand for registering policies as middleware.
+- `AllPolicies(...)`, `AnyPolicy(...)`, and `NotPolicy(...)` for composing reusable authorization rules without introducing a second execution pipeline.
+
+### Changed
+- Bot configuration mutators now treat the bot as configuration-frozen after the first run begins and ignore late mutation attempts for bot-level config such as prefixes, payload defaults, plugins, middleware, runners, localization, scene session wiring, and database context injection.
+- `MsgContext` godoc and field comments now describe the normalized update contract more explicitly, including when `Msg`, `From`, callback target fields, `Text`, and `Args` are expected to be populated.
+- `MsgContext` normalization now also carries `Chat` and `ChatID` for more Telegram update kinds, allowing policy and update handlers to rely on normalized chat identity outside message-only flows.
+- `MsgContext.Error(...)` and returned handler errors now suppress the automatic user reply when the error is explicitly marked with `AsInternalError(...)`, while keeping the previous user-visible default for unclassified errors.
+- Godoc, README examples, and regression-test naming now consistently describe the shared generic dependency model as app data, including `NoData` and `SetAppData(...)`.
+- Observer configuration now treats `SetObserver(nil)` as clearing instrumentation instead of leaving the previous observer attached.
+- Observer lifecycle events now cover generic update handlers and scene command, step, and message-fallback handlers with logical handler names and durations.
+- `RequirePolicy(...)` now emits `PolicyCheckedEvent` for both passed and denied policy decisions.
+- Scene command, step, and message-fallback flows now emit observer `ErrorEvent`s with scene-specific handler kinds and logical handler names.
+- Scene transition observer events now use the same transition payload for scene command, step, and message-fallback flows.
+- Observer error emission now also covers generic update handlers, callback payload decode failures, runner failures, and polling retries, including dedicated runner and polling handler kinds in `ErrorEvent`.
+- `TODO.md` and the framework backlog pages now mark the observability model as completed for `v1.0.0-rc.13`.
+- `tgapi.Chat.Type` now uses the typed `tgapi.ChatType` enum in public DTOs and tests instead of raw string casts.
+
+### Tests
+- Added regression coverage for the bot configuration freeze model, including ignored post-run mutations for core bot configuration methods and late registration paths.
+- Added table-driven update-contract coverage for `prepareUpdateCtx(...)`, including message-backed, callback-backed, user-backed, and no-user update kinds.
+- Added regression tests for policy middleware blocking, built-in private-chat policy decisions, normalized chat identity, and admin checks that use normalized `ChatID` and `FromID`.
+- Added regression tests for policy composition semantics, including all-of, any-of, and deny inversion with preserved internal failures.
+- Added regression tests for `SetObserver(...)`, `GetObserver()`, and clearing the observer with `SetObserver(nil)`.
+- Added observer regression tests for generic update-handler errors, callback payload decode failures, runner failure events, and polling retry emission.
+- Added observer regression tests for update and scene handler lifecycle events and `PolicyCheckedEvent` emission.
+- Added regression tests proving that `edited_message` and `edited_channel_post` stay out of command routing and continue through generic update handlers.
+- Added callback-routing regression tests for both chat-message and inline-message callback targets, including `CallbackQueryId`, `CallbackMsgId`, `InlineMsgId`, and payload-argument guarantees.
+- Added regression tests for the new error-visibility model in both message and callback flows, including silent internal-only errors and explicit user-visible callback replies.
+
+## v1.0.0-rc.12
+
+### Added
+- `AnswerLong(...)`, `AnswerLongf(...)`, `KeyboardLong(...)`, and `SplitMessageText(...)` for explicit plain-text splitting of long replies without changing the semantics of existing single-message helpers.
+- Centralized library-level validation errors in `errors.go`, including `ErrEmptyMessage`, `ErrMessageTooLong`, `ErrCaptionTooLong`, and context/target validation sentinels.
+- `Bot.GetPayloadType()`, `InlineKeyboard.GetPayloadType()`, and optional strict payload decoding via `BotOpts.StrictPayloadType` / `Bot.SetStrictPayloadType(...)`.
+- `MsgContext.BindArgs(...)` for binding positional command arguments into exported struct fields.
+- Binding sentinels `ErrBindArgsTargetNotPointer`, `ErrBindArgsTargetNotStruct`, `ErrBindArgsUnsupportedFieldType`, and `ErrBindArgsConversion`.
+- Work-in-progress scene/session support, including plugin scene registration, scoped scene sessions, scene entry/exit APIs on `MsgContext`, default in-memory session storage, scene-local routing before normal command handling, and state helpers on `SceneContext`.
+
+### Changed
+- `CommandExecutor` now returns `error`, and command, payload, and non-command update handlers now use centralized bot error handling for returned errors.
+- README and README_RU examples now use the new handler signature and document the long-message helpers.
+- README and README_RU now link to the project wiki, and the wiki now includes a page-priority tracker while content is being filled in.
+- README and README_RU now document scenes, session scopes, scene state helpers, and `SceneActionPass` semantics.
+- `TODO.md` and the framework backlog pages now group the remaining framework work into explicit priority 1, 2, and 3 buckets.
+- Payload-type comments and docs now distinguish between the bot's default payload type and keyboard-local overrides.
+- Scene runtime sentinel errors now have explicit godoc comments.
+- Public scene structs now document their exported fields more explicitly.
+- `MsgContext.Context()` now safely falls back to `context.Background()` when no request-scoped context is attached.
+- `MsgContext` reply, edit, callback, delete, action, and draft-limiter paths now use the context accessor instead of reaching into raw internal state.
+- Version constants were bumped to `v1.0.0-rc.12`.
+
+### Fixed
+- Message and caption validation now runs before Telegram API calls, rejecting empty messages, oversized message text, and oversized captions with stable sentinel errors.
+- Draft flushing and draft updates now reject oversized messages before sending invalid requests.
+- Callback payload decoding now optionally enforces strict type matching, while the default tolerant mode logs Base64-to-JSON decoding in debug mode and still accepts keyboard-local payload overrides.
+- Positional argument binding now leaves missing trailing struct fields at zero values, joins the remaining arguments into the final string field, and returns clearer binding errors.
+- Request-scoped contexts are now created per update handler execution and safely reused through `MsgContext.Context()` even for manually constructed test contexts.
+- Command and payload handlers now have regression coverage for end-to-end typed argument binding through the normal routing path.
+
+### Breaking Changes
+- `CommandExecutor[T]` changed from `func(ctx *MsgContext, db T)` to `func(ctx *MsgContext, db T) error`.
+- `Plugin.NewCommand(...)`, `Plugin.NewPayload(...)`, and `Plugin.AddUpdateHandler(...)` now require handlers with the new error-returning signature.
+
+### Tests
+- Added regression tests for `MsgContext.BindArgs(...)`, including scalar conversion, tail-string binding, zero-value trailing fields, invalid targets, unsupported field types, and end-to-end command/payload binding.
+- Added scene regression tests for runtime guards, scene-local command handling, and `SceneActionPass` preserving session state.
+- Added scene regression tests for message fallback handling, user-scoped session lookup without `Msg`, and custom `SessionStore` error propagation.
+
 ## v1.0.0-rc.11
 
 ### Fixed

README.md

@@ -4,12 +4,14 @@
 
 [![Go Version](https://img.shields.io/badge/Go-1.24+-00ADD8?logo=go&style=flat-square)](https://go.dev/)
 [![License: GPL-3.0](https://img.shields.io/badge/License-GPL%203.0-blue.svg?style=flat-square)](LICENSE)
-![Gitea Release](https://img.shields.io/gitea/v/release/ScuroNeko/Laniakea?gitea_url=https%3A%2F%2Fgit.nix13.pw&sort=semver&display_name=release&style=flat-square&color=purple&link=https%3A%2F%2Fgit.nix13.pw%2FScuroNeko%2FLaniakea%2Freleases)
+![Gitea Release](https://img.shields.io/gitea/v/release/ScuroNeko/Laniakea?gitea_url=https%3A%2F%2Fgit.scuroneko.dev&sort=semver&display_name=release&style=flat-square&color=purple&link=https%3A%2F%2Fgit.scuroneko.dev%2FScuroNeko%2FLaniakea%2Freleases)
 
 A lightweight, easy-to-use, and performant Telegram Bot API wrapper for Go. It simplifies bot development with a clean plugin system, middleware support, automatic command generation, and built-in rate limiting.
 
 [На русском](README_RU.md)
 
+[Wiki](https://git.scuroneko.dev/ScuroNeko/Laniakea/wiki)
+
 ---
 
 ## ✨ Features
@@ -19,15 +21,16 @@ A lightweight, easy-to-use, and performant Telegram Bot API wrapper for Go. It s
 *   **Middleware Support:** Run code before or after commands (e.g., logging, access control).
 *   **Automatic Command Generation:** Generate help and command lists automatically.
 *   **Built-in Rate Limiting:** Protect your bot from hitting Telegram API limits (supports `retry_after` handling).
-*   **Context-Aware:** Pass custom database or state contexts to your handlers.
+*   **Context-Aware:** Pass custom application data or state contexts to your handlers.
-*   **Fluent Interface:** Chain methods for clean configuration (e.g., `bot.ErrorTemplate(...).AddPlugins(...)`).
+*   **Configurable API:** Mix `Set...` and `Add...` helpers to configure bots clearly (for example, `bot.SetErrorTemplate(...).AddPlugins(...)`).
+*   **Polling and Webhook Runtime:** Run bots through long polling with `Run()` / `RunWithContext(...)` or through a bot-owned webhook server with `RunWebhookWithContext(...)`.
 
 ---
 
 ## 📦 Installation
 
 ```bash
-go get git.nix13.pw/scuroneko/laniakea
+go get git.scuroneko.dev/scuroneko/laniakea
 ```
 
 or
@@ -45,17 +48,18 @@ package main
 import (
 	"log"
 
-	"git.nix13.pw/scuroneko/laniakea" // Import the Laniakea library
+	"git.scuroneko.dev/scuroneko/laniakea" // Import the Laniakea library
 )
 
 // echo is a command handler function.
 // It receives two parameters:
 //   - ctx: the message context (contains info about the message, sender, chat, etc.)
-//   - db: your custom database context (here we use NoDB, a placeholder for no database)
+//   - data: your shared application data (here we use NoData, a placeholder for no shared data)
-func echo(ctx *laniakea.MsgContext, db laniakea.NoDB) {
+func echo(ctx *laniakea.MessageContext, data laniakea.NoData) error {
 	// Answer the user with the text they sent, without any command prefix.
 	// ctx.Text contains the user's message with the command part stripped off.
 	ctx.Answer(ctx.Text) // User input WITHOUT command
+	return nil
 }
 
 func main() {
@@ -63,8 +67,8 @@ func main() {
 	opts := &laniakea.BotOpts{Token: "TOKEN"}
 
 	// 2. Initialize a new bot instance.
-	//    We use laniakea.NoDB as the database context type (no database needed for this example).
+	//    We use laniakea.NoData as the application data type (no shared data needed for this example).
-	bot, err := laniakea.NewBot[laniakea.NoDB](opts)
+	bot, err := laniakea.NewBot[laniakea.NoData](opts)
 	if err != nil {
 		log.Fatal(err)
 	}
@@ -73,22 +77,23 @@ func main() {
 
 	// 3. Create a new plugin named "ping".
 	//    Plugins help group related commands and middlewares.
-	p := laniakea.NewPlugin[laniakea.NoDB]("ping")
+	p := laniakea.NewPlugin[laniakea.NoData]("ping")
 
 	// 4. Add a command to the plugin.
-	//    p.NewCommand(echo, "echo") creates a command that triggers the 'echo' function on the "/echo" command.
+	//    p.Command("echo", echo) creates a command that triggers the 'echo' function on the "/echo" command.
-	p.AddCommand(p.NewCommand(echo, "echo"))
+	p.Command("echo", echo)
 
 	// 5. Add another command using an anonymous function (closure).
 	//    This command simply replies "Pong" when the user sends "/ping".
-	p.AddCommand(p.NewCommand(func(ctx *laniakea.MsgContext, db laniakea.NoDB) {
+	p.Command("ping", func(ctx *laniakea.MessageContext, data laniakea.NoData) error {
 		ctx.Answer("Pong")
-	}, "ping"))
+		return nil
+	})
 
 	// 6. Configure the bot with a custom error template and add the plugin.
-	//    ErrorTemplate sets a format string for errors (where %s will be replaced by the actual error).
+	//    SetErrorTemplate sets a format string for errors (where %s will be replaced by the actual error).
 	//    AddPlugins(p) registers our "ping" plugin with the bot.
-	bot = bot.ErrorTemplate("Error\n\n%s").AddPlugins(p)
+	bot = bot.SetErrorTemplate("Error\n\n%s").AddPlugins(p)
 
 	// 7. Automatically generate commands like /start, /help, and a list of all registered commands.
 	//    This is optional but very useful for most bots.
@@ -105,14 +110,62 @@ func main() {
 
 ### How It Works
 1. `BotOpts`: Holds configuration like the API token.
-2. `NewBot[T]`: Creates a bot instance. The type parameter T allows you to pass a custom database context (e.g., *sql.DB) that will be available in all handlers. Use laniakea.NoDB if you don't need it.
+2. `NewBot[T]`: Creates a bot instance. The type parameter T allows you to pass custom shared application data (for example, *sql.DB or a service container) that will be available in all handlers. Use laniakea.NoData if you don't need it.
 3. `NewPlugin`: Creates a logical group for commands and middlewares.
-4. `AddCommand`: Registers a command. The first argument is the handler function (func(*MsgContext, T)), the second is the command name (without the slash).
+4. `Command`: Creates and registers a command. The first argument is the command name without the slash, the second is the handler function (`func(*MessageContext, T) error`).
-5. **Handler Functions**: Receive *MsgContext (message details, methods like Answer) and your custom database context T.
+5. **Handler Functions**: Receive *MessageContext (message details, methods like Answer) and your custom application data T, and return an error for centralized error handling.
-6. `ErrorTemplate`: Sets a template for error messages. The %s placeholder is replaced by the actual error.
+6. `SetErrorTemplate`: Sets a template for error messages. The %s placeholder is replaced by the actual error.
 7. `AutoGenerateCommands`: Registers plugin-defined commands with Telegram across the supported scopes.
 8. `Run()`: Starts the bot's update polling loop and returns an error if startup or polling fails.
-9. A `Bot` instance is single-use. After `Run()` or `RunWithContext()` returns, create a new bot instance for the next session.
+9. `RunWebhookWithContext(...)`: Starts the bot-owned webhook runtime when Telegram should deliver updates over HTTP instead of long polling.
+10. A `Bot` instance is single-use. After `Run()`, `RunWithContext()`, or `RunWebhookWithContext()` returns, create a new bot instance for the next session.
+
+## File-Based Config
+
+`BotOpts` can also be loaded from or saved to config files through the file codec API.
+
+Built in:
+- `BotOptsFileJSONCodec` for JSON files.
+
+Example:
+
+```go
+codec := laniakea.BotOptsFileJSONCodec{}
+opts, err := laniakea.LoadBotOptsFile(codec, "config.json")
+if err != nil {
+	log.Fatal(err)
+}
+
+bot, err := laniakea.NewBot[laniakea.NoData](opts)
+if err != nil {
+	log.Fatal(err)
+}
+```
+
+Placeholders like `{{ TG_TOKEN }}` inside the file are expanded from environment variables before decoding.
+
+You can also implement your own codec for other formats by satisfying `BotOptsFileCodec`.
+Only JSON is supported out of the box right now. If you want another format such as TOML, use `BotOptsFileJSONCodec` as the reference implementation for your own codec.
+
+See the full guide in the wiki: [Bot Options and Configuration](https://git.scuroneko.dev/ScuroNeko/Laniakea/wiki/Bot-Options-and-Configuration)
+
+## Webhook Runtime
+
+Laniakea also supports a bot-owned webhook runtime through `RunWebhookWithContext(...)` and `RunWebhook(...)`.
+
+Use it when:
+- Telegram should push updates to your HTTP endpoint instead of your bot polling for them.
+- You want webhook-delivered updates to reuse the same internal queue, worker pool, runners, and single-use lifecycle as polling.
+- You want Laniakea to register the webhook and own the local HTTP server.
+
+Production notes:
+- Set `BotWebhookOpts.SecretToken` for request authentication.
+- `BotWebhookOpts.SecretToken` is required when `BotWebhookOpts.UseStatusPath` is enabled.
+- Keep `BotWebhookOpts.Path` specific instead of serving webhook traffic on `/`.
+- If you switch an existing deployment from webhook mode to long polling, delete the webhook first with `CloseWebhook()` or `tgapi.DeleteWebhook(...)`. Telegram keeps webhook delivery active until it is removed.
+- Use `RunWebhookWithContext(...)` with a cancelable context, then call `Close()` after runtime shutdown.
+
+See the full guide in the wiki: [Webhook Runtime](https://git.scuroneko.dev/ScuroNeko/Laniakea/wiki/Webhook-Runtime)
 
 ## 📖 Core Concepts
 ### Plugins
@@ -120,7 +173,7 @@ func main() {
 Plugins are the main way to organize code. A plugin can have multiple commands and middlewares.
 ```go
 plugin := laniakea.NewPlugin[*MyDB]("admin")
-plugin.AddCommand(plugin.NewCommand(banUser, "ban"))
+plugin.Command("ban", banUser)
 bot.AddPlugins(plugin)
 ```
 
@@ -128,26 +181,29 @@ bot.AddPlugins(plugin)
 
 A command is a function that handles a specific bot command (e.g., /start).
 ```go
-func myHandler(ctx *laniakea.MsgContext, db *MyDB) {
+func myHandler(ctx *laniakea.MessageContext, db *MyDB) error {
     // Access command arguments via ctx.Args ([]string)
     // Reply to the user: ctx.Answer("some text")
+    return nil
 }
 ```
 
-### MsgContext
+### MessageContext
 
 Provides access to the incoming message and useful reply methods:
 
 - `Answer(text string) *AnswerMessage`: Sends a message with parse_mode none.
+- `AnswerLong(text string) []*AnswerMessage`: Splits long plain text into multiple messages.
 - `AnswerMarkdown(text string) *AnswerMessage`: Sends a message formatted with MarkdownV2 (you handle escaping).
 - `Keyboard(text string, keyboard *InlineKeyboard) *AnswerMessage`: Sends a message with parse_mode none and inline keyboard.
+- `KeyboardLong(text string, keyboard *InlineKeyboard) []*AnswerMessage`: Splits long plain text into multiple messages and attaches the keyboard to the final chunk.
 - `KeyboardMarkdown(text string, keyboard *InlineKeyboard) *AnswerMessage`: Sends a message formatted with MarkdownV2 (you handle escaping) and inline keyboard.
-- `AnswerPhoto(photoId, text string) *AnswerMessage`: Sends a message with photo with parse_mode none.
+- `AnswerPhoto(photoID, text string) *AnswerMessage`: Sends a message with photo with parse_mode none.
-- `AnswerPhotoMarkdown(photoId, text string) *AnswerMessage`: Sends a photo with MarkdownV2 caption (you handle escaping).
+- `AnswerPhotoMarkdown(photoID, text string) *AnswerMessage`: Sends a photo with MarkdownV2 caption (you handle escaping).
-- `EditCallback(text string)`: Edits message with parse_mode none after clicking inline button.
+- `EditCallback(text string, keyboard *InlineKeyboard) *AnswerMessage`: Edits message with parse_mode none after clicking inline button.
-- `EditCallbackMarkdown(text string)`: Edits a message formatted with MarkdownV2 (you handle escaping) after clicking inline button.
+- `EditCallbackMarkdown(text string, keyboard *InlineKeyboard) *AnswerMessage`: Edits a message formatted with MarkdownV2 (you handle escaping) after clicking inline button.
 - `SendAction(action tgapi.ChatActionType)`: Sends a “typing”, “uploading photo”, etc., action.
-- Fields: `Text`, `Args`, `From`, `FromID`, `Msg`, `InlineMsgId`, `CallbackQueryId`, etc.
+- Fields: `Text`, `Args`, `From`, `FromID`, `Msg`, `InlineMsgID`, `CallbackQueryID`, etc.
 - And more methods and fields!
 
 ### tgapi: API and Uploader
@@ -161,9 +217,9 @@ This split keeps method intent explicit: JSON-only calls go through `API`, file
 
 For advanced cases, `tgapi.NewRequest(...)` and `tgapi.NewUploaderRequest(...)` remain public as low-level escape hatches. They are intentionally less safe than method-specific helpers: callers must supply the correct Telegram method name and compatible request/response types themselves.
 
-### Database Context
+### App Data
 
-The `T` in `NewBot[T]` is a powerful feature. You can pass any type, but shared dependencies such as database pools should usually use a pointer type.
+The `T` in `NewBot[T]` is a powerful feature. You can pass any type, but shared dependencies such as database pools, service containers, or API clients should usually use a pointer type.
 
 ```go
 type MyDB struct { /* ... */ }
@@ -172,9 +228,79 @@ bot, err := laniakea.NewBot[*MyDB](opts)
 if err != nil {
     log.Fatal(err)
 }
-bot.DatabaseContext(db)
+bot.SetAppData(db)
 ```
 
+### Scenes and Sessions
+
+Scenes model multi-step conversations inside a plugin. Each active scene is stored in a session keyed by scope, so you can isolate flows per user, per chat, or per user-chat pair.
+
+```go
+plugin := laniakea.NewPlugin[MyDB]("signup")
+
+plugin.Scene("signup").
+    SetScope(laniakea.SceneScopeUserChat).
+    SetEntry("ask_name").
+    OnStep("ask_name", func(ctx *laniakea.SceneContext, db MyDB) (laniakea.SceneResult, error) {
+        if ctx.Text == "" {
+            ctx.Answer("What is your name?")
+            return ctx.Stay(), nil
+        }
+
+        if err := ctx.SaveData(struct {
+            Name string `json:"name"`
+        }{Name: ctx.Text}); err != nil {
+            return laniakea.SceneResult{}, err
+        }
+
+        ctx.Answer("Nice to meet you.")
+        return ctx.Next("done"), nil
+    }).
+    OnStep("done", func(ctx *laniakea.SceneContext, db MyDB) (laniakea.SceneResult, error) {
+        return ctx.Exit(), nil
+    })
+```
+
+- Use `ctx.EnterScene("signup")` to enter the configured entry step.
+- Use `ctx.EnterSceneStep("signup", "done")` when you need an explicit starting step.
+- Return `ctx.Stay()`, `ctx.Next(step)`, `ctx.Exit()`, or `ctx.Pass()` from scene handlers to control flow.
+- `SceneActionPass` keeps the current session unchanged and continues normal bot routing.
+- Use `SceneContext.SaveData(...)` and `SceneContext.BindData(...)` for JSON session state.
+- Use `SceneScopeUser`, `SceneScopeChat`, or `SceneScopeUserChat` depending on how widely a conversation should be shared.
+
+## ⏱️ Runners
+
+Runners are background tasks that execute alongside the bot runtime. They are registered before the bot starts and launched automatically when the bot starts.
+
+```go
+import "time"
+
+// One-shot runner — fires once in a goroutine when the bot starts (default).
+bot.AddRunner(
+    laniakea.NewRunner("seed-cache", func(b *laniakea.Bot[*MyDB]) error {
+        return b.GetAppData().SeedCache()
+    }),
+)
+
+// Periodic runner — fires every 10 minutes in a goroutine.
+bot.AddRunner(
+    laniakea.NewRunner("refresh-stats", func(b *laniakea.Bot[*MyDB]) error {
+        return b.GetAppData().RefreshStats()
+    }).Every(10 * time.Minute),
+)
+
+// Synchronous one-shot — blocks runtime startup until it completes.
+bot.AddRunner(
+    laniakea.NewRunner("migrate", func(b *laniakea.Bot[*MyDB]) error {
+        return b.GetAppData().Migrate()
+    }).Async(false),
+)
+```
+
+Builder methods:
+- `Async(bool) *Runner[T]` — if `true` (default), runs in a goroutine; if `false`, blocks runtime startup.
+- `Every(time.Duration) *Runner[T]` — sets the repeat interval. Zero (default) means run once; positive value repeats. Periodic runners require `Async(true)`.
+
 ## 🧩 Middleware
 Middleware are functions that run before a command handler. They are perfect for cross-cutting concerns like logging, access control, rate limiting, or modifying the context.
 
@@ -182,7 +308,7 @@ Middleware are functions that run before a command handler. They are perfect for
 A middleware function has the same signature as a command handler, but it must return a bool:
 
 ```go
-func(ctx *MsgContext, db T) bool
+func(ctx *MessageContext, db T) bool
 ```
 
 - If it returns true, the next middleware (or the command) will be executed.
@@ -195,14 +321,14 @@ Use `AddMiddleware` on a plugin to add one or more shared middleware functions.
 plugin := laniakea.NewPlugin[*MyDB]("admin")
 plugin.AddMiddleware(laniakea.NewMiddleware("logging", loggingMiddleware))
 plugin.AddMiddleware(laniakea.NewMiddleware("admin-only", adminOnlyMiddleware))
-plugin.AddCommand(plugin.NewCommand(banUser, "ban"))
+plugin.Command("ban", banUser)
 ```
 
 ### Example Middlewares
 
 1. Logging Middleware – logs every command execution.
 ```go
-func loggingMiddleware(ctx *laniakea.MsgContext, db *MyDB) bool {
+func loggingMiddleware(ctx *laniakea.MessageContext, db *MyDB) bool {
     log.Printf("User %d executed command: %s", ctx.FromID, ctx.Msg.Text)
     return true // continue to next middleware/command
 }
@@ -210,7 +336,7 @@ func loggingMiddleware(ctx *laniakea.MsgContext, db *MyDB) bool {
 
 2. Admin-Only Middleware – restricts access to users with a specific role.
 ```go
-func adminOnlyMiddleware(ctx *laniakea.MsgContext, db *MyDB) bool {
+func adminOnlyMiddleware(ctx *laniakea.MessageContext, db *MyDB) bool {
     if !db.IsAdmin(ctx.FromID) { // assume db has IsAdmin method
         ctx.Answer("⛔ Access denied. Admins only.")
         return false // stop execution
@@ -220,14 +346,14 @@ func adminOnlyMiddleware(ctx *laniakea.MsgContext, db *MyDB) bool {
 ```
 
 ### Important Notes
-- Middleware can modify the MsgContext (e.g., add custom fields) before the command runs.
+- Middleware can modify the MessageContext (e.g., add custom fields) before the command runs.
 
 ## ⚙️ Advanced Configuration
-- **Inline Keyboards**: Build keyboards using `laniakea.NewInlineKeyboardJson`, `laniakea.NewInlineKeyboardBase64`, or `laniakea.NewInlineKeyboard`.
+- **Inline Keyboards**: Build keyboards using `laniakea.NewInlineKeyboardJSON`, `laniakea.NewInlineKeyboardBase64`, or `laniakea.NewInlineKeyboard`. `Bot.SetPayloadType(...)` defines the default payload format, and `InlineKeyboard.SetPayloadType(...)` overrides it for one keyboard.
 - **Rate Limiting**: Pass a configured utils.RateLimiter via BotOpts to handle Telegram's rate limits gracefully.
 - **Localization**: `L10n` is safe for concurrent use once attached to the bot.
 - **Custom Update Handlers**: Use `plugin.AddUpdateHandler(...)` for Telegram update types that are not part of the command/payload flow.
-- **Lifecycle**: `RunWithContext(...)` does not call `Close()` for you. Shut the bot down explicitly, and create a fresh `Bot` for the next run.
+- **Lifecycle**: `RunWithContext(...)` and `RunWebhookWithContext(...)` do not call `Close()` for you. Shut the bot down explicitly, and create a fresh `Bot` for the next run.
 
 ## Telegram Update Handling
 - Commands and payloads are handled through plugins.
@@ -240,7 +366,9 @@ func adminOnlyMiddleware(ctx *laniakea.MsgContext, db *MyDB) bool {
 This project is licensed under the GNU General Public License v3.0 — see the [LICENSE](LICENSE) file for details.
 
 ## 📚 Learn More
-[GoDoc](https://pkg.go.dev/git.nix13.pw/scuroneko/laniakea)
+[GoDoc](https://pkg.go.dev/git.scuroneko.dev/scuroneko/laniakea)
+
+[Wiki](https://git.scuroneko.dev/ScuroNeko/Laniakea/wiki)
 
 [Telegram Bot API](https://core.telegram.org/bots/api)
 

README_RU.md

@@ -4,12 +4,14 @@
 
 [![Go Version](https://img.shields.io/badge/Go-1.24+-00ADD8?logo=go&style=flat-square)](https://go.dev/)
 [![License: GPL-3.0](https://img.shields.io/badge/License-GPL%203.0-blue.svg?style=flat-square)](LICENSE)
-![Gitea Release](https://img.shields.io/gitea/v/release/ScuroNeko/Laniakea?gitea_url=https%3A%2F%2Fgit.nix13.pw&sort=semver&display_name=release&style=flat-square&color=purple&link=https%3A%2F%2Fgit.nix13.pw%2FScuroNeko%2FLaniakea%2Freleases)
+![Gitea Release](https://img.shields.io/gitea/v/release/ScuroNeko/Laniakea?gitea_url=https%3A%2F%2Fgit.scuroneko.dev&sort=semver&display_name=release&style=flat-square&color=purple&link=https%3A%2F%2Fgit.scuroneko.dev%2FScuroNeko%2FLaniakea%2Freleases)
 
 Легковесная, простая в использовании и производительная обёртка для Telegram Bot API на Go. Она упрощает разработку ботов благодаря чистой системе плагинов, поддержке Middleware, автоматической генерации команд и встроенному рейтлимитеру.
 
 [English](README.md)
 
+[Wiki](https://git.scuroneko.dev/ScuroNeko/Laniakea/wiki)
+
 ---
 
 ## ✨ Возможности
@@ -20,15 +22,16 @@
 *   **Поддержка промежуточных слоёв (Middleware):** Выполняйте код до или после команд (например, логирование, проверка доступа).
 *   **Автоматическая генерация команд:** Генерируйте справку и списки команд автоматически.
 *   **Встроенный ограничитель запросов (Rate Limiter):** Защитите бота от превышения лимитов Telegram API (с обработкой `retry_after`).
-*   **Контекст данных:** Передавайте свой контекст базы данных или состояния в обработчики.
+*   **Контекст данных:** Передавайте общие данные приложения или state в обработчики.
-*   **Текучий интерфейс (Fluent Interface):** Стройте цепочки методов для чистой конфигурации (например, `bot.ErrorTemplate(...).AddPlugins(...)`).
+*   **Настраиваемый API:** Комбинируйте `Set...` и `Add...` helper-методы для понятной конфигурации, например `bot.SetErrorTemplate(...).AddPlugins(...)`.
+*   **Polling и Webhook Runtime:** Запускайте бота через long polling с `Run()` / `RunWithContext(...)` или через webhook server, которым владеет сам бот, с `RunWebhookWithContext(...)`.
 
 ---
 
 ## 📦 Установка
 
 ```bash
-go get git.nix13.pw/scuroneko/laniakea
+go get git.scuroneko.dev/scuroneko/laniakea
 ```
 
 или
@@ -46,17 +49,18 @@ package main
 import (
 	"log"
 
-	"git.nix13.pw/scuroneko/laniakea" // Импортируем библиотеку Laniakea
+	"git.scuroneko.dev/scuroneko/laniakea" // Импортируем библиотеку Laniakea
 )
 
 // echo — это функция-обработчик команды.
 // Она получает два параметра:
 //   - ctx: контекст сообщения (содержит информацию о сообщении, отправителе, чате и т.д.)
-//   - db: ваш пользовательский контекст базы данных (здесь мы используем NoDB — заглушку)
+//   - data: ваши общие данные приложения (здесь мы используем NoData — заглушку без общих зависимостей)
-func echo(ctx *laniakea.MsgContext, db laniakea.NoDB) {
+func echo(ctx *laniakea.MessageContext, data laniakea.NoData) error {
 	// Отвечаем пользователю текстом, который он прислал, без префикса команды.
 	// ctx.Text содержит сообщение пользователя, из которого удалена часть с командой.
 	ctx.Answer(ctx.Text) // Ввод пользователя БЕЗ команды
+	return nil
 }
 
 func main() {
@@ -64,8 +68,8 @@ func main() {
 	opts := &laniakea.BotOpts{Token: "TOKEN"}
 
 	// 2. Инициализируем новый экземпляр бота.
-	//    Используем laniakea.NoDB как тип контекста базы данных (база не нужна для примера).
+	//    Используем laniakea.NoData как тип данных приложения (общие зависимости не нужны для примера).
-	bot, err := laniakea.NewBot[laniakea.NoDB](opts)
+	bot, err := laniakea.NewBot[laniakea.NoData](opts)
 	if err != nil {
 		log.Fatal(err)
 	}
@@ -74,22 +78,23 @@ func main() {
 
 	// 3. Создаём новый плагин с именем "ping".
 	//    Плагины помогают группировать связанные команды и промежуточные обработчики.
-	p := laniakea.NewPlugin[laniakea.NoDB]("ping")
+	p := laniakea.NewPlugin[laniakea.NoData]("ping")
 
 	// 4. Добавляем команду в плагин.
-	//    p.NewCommand(echo, "echo") создаёт команду, которая вызывает функцию 'echo' по команде "/echo".
+	//    p.Command("echo", echo) создаёт команду, которая вызывает функцию 'echo' по команде "/echo".
-	p.AddCommand(p.NewCommand(echo, "echo"))
+	p.Command("echo", echo)
 
 	// 5. Добавляем ещё одну команду, используя анонимную функцию (замыкание).
 	//    Эта команда просто отвечает "Pong", когда пользователь отправляет "/ping".
-	p.AddCommand(p.NewCommand(func(ctx *laniakea.MsgContext, db laniakea.NoDB) {
+	p.Command("ping", func(ctx *laniakea.MessageContext, data laniakea.NoData) error {
 		ctx.Answer("Pong")
-	}, "ping"))
+		return nil
+	})
 
 	// 6. Настраиваем бота: задаём шаблон ошибки и добавляем плагин.
-	//    ErrorTemplate устанавливает формат для сообщений об ошибках (где %s будет заменён на текст ошибки).
+	//    SetErrorTemplate устанавливает формат для сообщений об ошибках (где %s будет заменён на текст ошибки).
 	//    AddPlugins(p) регистрирует наш плагин "ping" в боте.
-	bot = bot.ErrorTemplate("Ошибка\n\n%s").AddPlugins(p)
+	bot = bot.SetErrorTemplate("Ошибка\n\n%s").AddPlugins(p)
 
 	// 7. Автоматически генерируем команды, такие как /start, /help и список всех зарегистрированных команд.
 	//    Это необязательно, но очень полезно для большинства ботов.
@@ -106,14 +111,62 @@ func main() {
 
 ### Как это работает
 1. `BotOpts`: Содержит конфигурацию, например, токен API.
-2. `NewBot[T]`: Создаёт экземпляр бота. Параметр типа T позволяет передать пользовательский контекст базы данных (например, *sql.DB), который будет доступен во всех обработчиках. Используйте laniakea.NoDB, если он не нужен.
+2. `NewBot[T]`: Создаёт экземпляр бота. Параметр типа T позволяет передать общие данные приложения (например, *sql.DB или контейнер сервисов), которые будут доступны во всех обработчиках. Используйте laniakea.NoData, если они не нужны.
 3. `NewPlugin`: Создаёт логическую группу для команд и Middleware.
-4. `AddCommand`: Регистрирует команду. Первый аргумент — функция-обработчик (func(*MsgContext, T)), второй — имя команды (без слеша).
+4. `Command`: Создаёт и регистрирует команду. Первый аргумент — имя команды без слеша, второй — функция-обработчик (`func(*MessageContext, T) error`).
-5. **Функции-обработчики**: Получают *MsgContext (детали сообщения, методы типа Answer) и ваш контекст базы данных T.
+5. **Функции-обработчики**: Получают *MessageContext (детали сообщения, методы типа Answer) и ваши данные приложения типа T, а ошибку возвращают для централизованной обработки.
-6. `ErrorTemplate`: Устанавливает шаблон для сообщений об ошибках. Плейсхолдер %s заменяется на текст ошибки.
+6. `SetErrorTemplate`: Устанавливает шаблон для сообщений об ошибках. Плейсхолдер %s заменяется на текст ошибки.
 7. `AutoGenerateCommands`: Регистрирует команды из плагинов в Telegram для поддерживаемых scope.
 8. `Run()`: Запускает цикл опроса обновлений бота и возвращает ошибку, если старт или polling завершился неуспешно.
-9. Экземпляр `Bot` одноразовый. После завершения `Run()` или `RunWithContext()` для следующего запуска создавайте новый бот.
+9. `RunWebhookWithContext(...)`: Запускает bot-owned webhook runtime, когда Telegram должен доставлять update по HTTP вместо long polling.
+10. Экземпляр `Bot` одноразовый. После завершения `Run()`, `RunWithContext()` или `RunWebhookWithContext()` для следующего запуска создавайте новый бот.
+
+## Конфиг из файла
+
+`BotOpts` можно не только собирать вручную или из environment, но и загружать и сохранять через file codec API.
+
+Из коробки доступно:
+- `BotOptsFileJSONCodec` для JSON-файлов.
+
+Пример:
+
+```go
+codec := laniakea.BotOptsFileJSONCodec{}
+opts, err := laniakea.LoadBotOptsFile(codec, "config.json")
+if err != nil {
+	log.Fatal(err)
+}
+
+bot, err := laniakea.NewBot[laniakea.NoData](opts)
+if err != nil {
+	log.Fatal(err)
+}
+```
+
+Плейсхолдеры вида `{{ TG_TOKEN }}` внутри файла перед декодированием разворачиваются из переменных окружения.
+
+Для других форматов можно реализовать собственный codec через интерфейс `BotOptsFileCodec`.
+Из коробки сейчас поддерживается только JSON. Если нужен другой формат, например TOML, используй `BotOptsFileJSONCodec` как эталонную реализацию собственного codec.
+
+Подробности есть в wiki: [Bot Options and Configuration RU](https://git.scuroneko.dev/ScuroNeko/Laniakea/wiki/Bot-Options-and-Configuration-RU)
+
+## Webhook Runtime
+
+Laniakea также поддерживает bot-owned webhook runtime через `RunWebhookWithContext(...)` и `RunWebhook(...)`.
+
+Используй его, когда:
+- Telegram должен сам отправлять update на твой HTTP endpoint вместо polling.
+- Ты хочешь, чтобы webhook-update проходили через ту же внутреннюю очередь, тот же worker pool, тех же runners и тот же single-use lifecycle, что и polling.
+- Ты хочешь, чтобы Laniakea сама регистрировала webhook и владела локальным HTTP server.
+
+Практические замечания:
+- Задавай `BotWebhookOpts.SecretToken` для аутентификации запросов.
+- Непустой `BotWebhookOpts.SecretToken` обязателен, если включён `BotWebhookOpts.UseStatusPath`.
+- Используй явный `BotWebhookOpts.Path`, а не `/`.
+- Если ты переводишь уже существующий deployment с webhook-режима на long polling, сначала удали webhook через `CloseWebhook()` или `tgapi.DeleteWebhook(...)`. Пока webhook не удалён, Telegram продолжает доставку через него.
+- Запускай `RunWebhookWithContext(...)` с cancelable context и после остановки runtime всё равно вызывай `Close()`.
+
+Полное руководство есть в wiki: [Webhook Runtime](https://git.scuroneko.dev/ScuroNeko/Laniakea/wiki/Webhook-Runtime-RU)
 
 ## 📖 Основные концепции
 ### Плагины (Plugins)
@@ -121,7 +174,7 @@ func main() {
 
 ```go
 plugin := laniakea.NewPlugin[*MyDB]("admin")
-plugin.AddCommand(plugin.NewCommand(banUser, "ban"))
+plugin.Command("ban", banUser)
 bot.AddPlugins(plugin)
 ```
 
@@ -129,29 +182,32 @@ bot.AddPlugins(plugin)
 Команда — это функция, которая обрабатывает конкретную команду бота (например, /start).
 
 ```go
-func myHandler(ctx *laniakea.MsgContext, db *MyDB) {
+func myHandler(ctx *laniakea.MessageContext, db *MyDB) error {
     // Доступ к аргументам команды через ctx.Args ([]string)
     // Ответ пользователю: ctx.Answer("какой-то текст")
+    return nil
 }
 ```
 
-### Контекст сообщения (MsgContext)
+### Контекст сообщения (MessageContext)
 Предоставляет доступ к входящему сообщению и полезные методы для ответа:
 
 - `Answer(text string)`: Отправляет сообщение с parse_mode none.
+- `AnswerLong(text string) []*AnswerMessage`: Разбивает длинный plain text на несколько сообщений.
 - `AnswerMarkdown(text string)`: Отправляет сообщение, отформатированное MarkdownV2 (экранирование на вашей стороне).
 - `Keyboard(text string, keyboard *InlineKeyboard) *AnswerMessage`: Отправляет сообщение с parse_mode none и Inline клавиатурой.
+- `KeyboardLong(text string, keyboard *InlineKeyboard) []*AnswerMessage`: Разбивает длинный plain text на несколько сообщений и вешает клавиатуру на последний chunk.
 - `KeyboardMarkdown(text string, keyboard *InlineKeyboard) *AnswerMessage`: Отправляет сообщение, отформатированное MarkdownV2 (экранирование на вашей стороне), и Inline клавиатурой.
-- `AnswerPhoto(photoId, text string) *AnswerMessage`: Отправляет фотографию с подписью и parse_mode none.
+- `AnswerPhoto(photoID, text string) *AnswerMessage`: Отправляет фотографию с подписью и parse_mode none.
-- `AnswerPhotoMarkdown(photoId, text string) *AnswerMessage`: Отправляет фотографию с подписью, отформатированной MarkdownV2 (экранирование на вашей стороне).
+- `AnswerPhotoMarkdown(photoID, text string) *AnswerMessage`: Отправляет фотографию с подписью, отформатированной MarkdownV2 (экранирование на вашей стороне).
-- `EditCallback(text string)`: Редактирует сообщение с `parse_mode` none после нажатия inline-кнопки.
+- `EditCallback(text string, keyboard *InlineKeyboard) *AnswerMessage`: Редактирует сообщение с `parse_mode` none после нажатия inline-кнопки.
-- `EditCallbackMarkdown(text string)`: Редактирует сообщение в формате MarkdownV2 (экранирование на вашей стороне) после нажатия inline-кнопки.
+- `EditCallbackMarkdown(text string, keyboard *InlineKeyboard) *AnswerMessage`: Редактирует сообщение в формате MarkdownV2 (экранирование на вашей стороне) после нажатия inline-кнопки.
 - `SendAction(action tgapi.ChatActionType)`: Отправляет действие "печатает", "загружает фото" и т.д.
-- Поля: `Text`, `Args`, `From`, `FromID`, `Msg`, `InlineMsgId`, `CallbackQueryId` и другие.
+- Поля: `Text`, `Args`, `From`, `FromID`, `Msg`, `InlineMsgID`, `CallbackQueryID` и другие.
 - И много других методов и полей!
 
-### Контекст базы данных (Database Context)
+### App Data
-Параметр типа `T` в `NewBot[T]` — мощная функция. Вы можете передать любой тип, но для разделяемых зависимостей вроде пула соединений с БД обычно стоит использовать pointer type.
+Параметр типа `T` в `NewBot[T]` — мощная возможность. Вы можете передать любой тип, но для разделяемых зависимостей вроде пула соединений с БД, контейнера сервисов или API-клиента обычно стоит использовать pointer type.
 
 ```go
 type MyDB struct { /* ... */ }
@@ -160,9 +216,79 @@ bot, err := laniakea.NewBot[*MyDB](opts)
 if err != nil {
     log.Fatal(err)
 }
-bot.DatabaseContext(db)
+bot.SetAppData(db)
 ```
 
+### Сцены и сессии (Scenes and Sessions)
+
+Сцены описывают многошаговые диалоги внутри плагина. Активная сцена хранится в session state, ключ которого зависит от scope, поэтому поток можно изолировать на пользователя, на чат или на пару пользователь-чат.
+
+```go
+plugin := laniakea.NewPlugin[MyDB]("signup")
+
+plugin.Scene("signup").
+    SetScope(laniakea.SceneScopeUserChat).
+    SetEntry("ask_name").
+    OnStep("ask_name", func(ctx *laniakea.SceneContext, db MyDB) (laniakea.SceneResult, error) {
+        if ctx.Text == "" {
+            ctx.Answer("Как тебя зовут?")
+            return ctx.Stay(), nil
+        }
+
+        if err := ctx.SaveData(struct {
+            Name string `json:"name"`
+        }{Name: ctx.Text}); err != nil {
+            return laniakea.SceneResult{}, err
+        }
+
+        ctx.Answer("Приятно познакомиться.")
+        return ctx.Next("done"), nil
+    }).
+    OnStep("done", func(ctx *laniakea.SceneContext, db MyDB) (laniakea.SceneResult, error) {
+        return ctx.Exit(), nil
+    })
+```
+
+- Используйте `ctx.EnterScene("signup")`, чтобы войти в entry step, настроенный у сцены.
+- Используйте `ctx.EnterSceneStep("signup", "done")`, если нужен явный стартовый step.
+- Из scene handler возвращайте `ctx.Stay()`, `ctx.Next(step)`, `ctx.Exit()` или `ctx.Pass()` для управления потоком.
+- `SceneActionPass` не меняет текущую session state и продолжает обычный routing бота.
+- Для JSON-состояния сцены используйте `SceneContext.SaveData(...)` и `SceneContext.BindData(...)`.
+- Выбирайте `SceneScopeUser`, `SceneScopeChat` или `SceneScopeUserChat` в зависимости от того, насколько широко должен разделяться диалог.
+
+## ⏱️ Раннеры (Runners)
+
+Раннеры — фоновые задачи, которые выполняются вместе с bot runtime. Они регистрируются до запуска бота и автоматически запускаются при старте.
+
+```go
+import "time"
+
+// Одноразовый раннер — запускается один раз в горутине при старте (по умолчанию).
+bot.AddRunner(
+    laniakea.NewRunner("seed-cache", func(b *laniakea.Bot[*MyDB]) error {
+        return b.GetAppData().SeedCache()
+    }),
+)
+
+// Периодический раннер — запускается каждые 10 минут в горутине.
+bot.AddRunner(
+    laniakea.NewRunner("refresh-stats", func(b *laniakea.Bot[*MyDB]) error {
+        return b.GetAppData().RefreshStats()
+    }).Every(10 * time.Minute),
+)
+
+// Синхронный одноразовый — блокирует запуск runtime до завершения.
+bot.AddRunner(
+    laniakea.NewRunner("migrate", func(b *laniakea.Bot[*MyDB]) error {
+        return b.GetAppData().Migrate()
+    }).Async(false),
+)
+```
+
+Методы builder:
+- `Async(bool) *Runner[T]` — если `true` (по умолчанию), запускается в горутине; если `false`, блокирует запуск runtime.
+- `Every(time.Duration) *Runner[T]` — задаёт интервал повторного запуска. Ноль (по умолчанию) означает одноразовый запуск; положительное значение — периодический. Периодические раннеры требуют `Async(true)`.
+
 ### tgapi: API и Uploader
 
 В `tgapi` есть два клиента:
@@ -179,7 +305,7 @@ Middleware — это функции, которые выполняются пе
 Функция middleware имеет ту же сигнатуру, что и обработчик команды, но должна возвращать bool:
 
 ```go
-func(ctx *MsgContext, db T) bool
+func(ctx *MessageContext, db T) bool
 ```
 
 - Если возвращается true, выполняется следующий middleware (или сама команда).
@@ -192,14 +318,14 @@ func(ctx *MsgContext, db T) bool
 plugin := laniakea.NewPlugin[*MyDB]("admin")
 plugin.AddMiddleware(laniakea.NewMiddleware("logging", loggingMiddleware))
 plugin.AddMiddleware(laniakea.NewMiddleware("admin-only", adminOnlyMiddleware))
-plugin.AddCommand(plugin.NewCommand(banUser, "ban"))
+plugin.Command("ban", banUser)
 ```
 
 ### Примеры middleware
 
 1. Логирующий middleware – логирует каждое выполнение команды.
 ```go
-func loggingMiddleware(ctx *laniakea.MsgContext, db *MyDB) bool {
+func loggingMiddleware(ctx *laniakea.MessageContext, db *MyDB) bool {
     log.Printf("Пользователь %d выполнил команду: %s", ctx.FromID, ctx.Msg.Text)
     return true // продолжаем к следующему middleware/команде
 }
@@ -207,7 +333,7 @@ func loggingMiddleware(ctx *laniakea.MsgContext, db *MyDB) bool {
 
 2. Middleware только для администраторов – ограничивает доступ пользователям с определённой ролью.
 ```go
-func adminOnlyMiddleware(ctx *laniakea.MsgContext, db *MyDB) bool {
+func adminOnlyMiddleware(ctx *laniakea.MessageContext, db *MyDB) bool {
     if !db.IsAdmin(ctx.FromID) { // предполагается, что db имеет метод IsAdmin
         ctx.Answer("⛔ Доступ запрещён. Только для администраторов.")
         return false // останавливаем выполнение
@@ -217,14 +343,14 @@ func adminOnlyMiddleware(ctx *laniakea.MsgContext, db *MyDB) bool {
 ```
 
 ### Важные замечания
-- Middleware может изменять MsgContext (например, добавлять пользовательские поля) перед запуском команды.
+- Middleware может изменять MessageContext (например, добавлять пользовательские поля) перед запуском команды.
 
 ## ⚙️ Расширенная настройка
-- **Инлайн-клавиатуры**: Создавайте клавиатуры с помощью `laniakea.NewInlineKeyboardJson`, `laniakea.NewInlineKeyboardBase64` или `laniakea.NewInlineKeyboard`.
+- **Инлайн-клавиатуры**: Создавайте клавиатуры с помощью `laniakea.NewInlineKeyboardJSON`, `laniakea.NewInlineKeyboardBase64` или `laniakea.NewInlineKeyboard`. `Bot.SetPayloadType(...)` задаёт payload format по умолчанию, а `InlineKeyboard.SetPayloadType(...)` переопределяет его для конкретной клавиатуры.
 - **Ограничение запросов**: Передайте настроенный `utils.RateLimiter` через `BotOpts` для корректной обработки лимитов Telegram.
 - **Локализация**: `L10n` безопасен для конкурентного использования после подключения к боту.
 - **Пользовательские update handlers**: Используйте `plugin.AddUpdateHandler(...)` для Telegram update types вне command/payload flow.
-- **Жизненный цикл**: `RunWithContext(...)` не вызывает `Close()` автоматически. Завершайте бот явно и создавайте новый `Bot` для следующего запуска.
+- **Жизненный цикл**: `RunWithContext(...)` и `RunWebhookWithContext(...)` не вызывают `Close()` автоматически. Завершайте бот явно и создавайте новый `Bot` для следующего запуска.
 
 ## Обработка Telegram Updates
 - Команды и payload-ы обрабатываются через плагины.
@@ -236,7 +362,9 @@ func adminOnlyMiddleware(ctx *laniakea.MsgContext, db *MyDB) bool {
 Этот проект лицензирован под GNU General Public License v3.0 - подробности см. в файле [LICENSE](LICENSE).
 
 ## 📚 Дополнительная информация
-[GoDoc Laniakea](https://pkg.go.dev/git.nix13.pw/scuroneko/laniakea)
+[GoDoc Laniakea](https://pkg.go.dev/git.scuroneko.dev/scuroneko/laniakea)
+
+[Wiki](https://git.scuroneko.dev/ScuroNeko/Laniakea/wiki)
 
 [Telegram Bot API](https://core.telegram.org/bots/api)
 

TODO.md

@@ -0,0 +1,30 @@
+# TODO
+
+---
+
+The framework backlog has moved to the wiki.
+
+Primary page:
+
+- https://git.scuroneko.dev/ScuroNeko/Laniakea/wiki/Framework-Backlog
+
+Russian page:
+
+- https://git.scuroneko.dev/ScuroNeko/Laniakea/wiki/Framework-Backlog-RU
+
+Current priority split:
+
+- `Partial`: none.
+- `Ideas`: service layer and dependency graph model, plugin composition contract.
+
+Completed former high-priority items:
+
+- `[v1.0.0-rc.14] Webhook runtime model.`
+- `[v1.0.0-rc.13] Observability model`: added first-class `Observer` events for update, command, payload, scene, policy, runner, polling, and centralized error flows, with safe event dispatch and regression coverage for the new runtime hooks.
+- `[v1.0.0-rc.13] Authorization and policy model`: added first-class `Policy[T]`, middleware integration through `RequirePolicy(...)`, plugin and bot policy registration helpers, built-in Telegram-aware policies, and composable `AllPolicies(...)`, `AnyPolicy(...)`, and `NotPolicy(...)` helpers with regression coverage.
+- `[v1.0.0-rc.13] Update schema contract`: documented and tested the normalized `MsgContext` update-routing contract, including routing categories and per-update field guarantees.
+- `[v1.0.0-rc.13] User-facing vs internal error model`: added explicit user-visible vs internal-only error markers and updated centralized handler error routing accordingly.
+- `[v1.0.0-rc.13] Configuration freeze model`: formalized bot configuration freeze after first run, documented lifecycle commit points, and added regression coverage for ignored late mutations.
+- `[v1.0.0-rc.12] Conversation / Scene Model`.
+- `[v1.0.0-rc.12] Typed Handler Input Model`.
+- `[v1.0.0-rc.12] Request Context / Cancellation Model`.

bot.go

@@ -4,21 +4,21 @@ import (
 	"context"
 	"errors"
 	"fmt"
-	"reflect"
+	"net/http"
-	"sort"
-	"strings"
 	"sync"
 	"time"
 
-	"git.nix13.pw/scuroneko/extypes"
+	"git.scuroneko.dev/scuroneko/extypes"
-	"git.nix13.pw/scuroneko/laniakea/tgapi"
+	"git.scuroneko.dev/scuroneko/laniakea/tgapi"
-	"git.nix13.pw/scuroneko/laniakea/utils"
+	"git.scuroneko.dev/scuroneko/laniakea/utils"
-	"git.nix13.pw/scuroneko/slog"
+	"git.scuroneko.dev/scuroneko/sneklog/v2"
-	"github.com/alitto/pond/v2"
 )
 
-// DbContext is the generic dependency type injected into bots, plugins, and handlers.
+// AppData is the generic shared application data type injected into bots,
-// Use it for shared application state such as database handles or service containers.
+// plugins, and handlers.
+//
+// Use it for long-lived shared dependencies such as database handles, service
+// containers, API clients, or immutable configuration snapshots.
 //
 // Example:
 //
@@ -28,27 +28,35 @@ import (
 //	if err != nil {
 //		return err
 //	}
-//	bot.DatabaseContext(myDB)
+//	bot.SetAppData(myDB)
 //
-// Use NoDB if no database is needed.
+// Use NoData if no shared application data is needed.
-type DbContext any
+type AppData any
 
-// NoDB is a placeholder type for bots that do not use a database.
+// NoData is a placeholder type for bots that do not use shared application
-// Use Bot[NoDB] to indicate no dependency injection is required.
+// data.
-type NoDB struct{ DbContext }
+//
+// Use Bot[NoData] to indicate no shared dependency injection is required.
+type NoData struct{}
 
-// DbLogger is a function type that returns a slog.LoggerWriter for database logging.
+// AppDataLogger builds a sneklog.LoggerWriter from injected application data.
-// Used to inject database-specific log output (e.g., SQL queries, ORM events).
+//
-type DbLogger[T DbContext] func(db T) slog.LoggerWriter
+// Use it when shared application data exposes a log sink or adapter that should
+// receive framework logs.
+type AppDataLogger[T AppData] func(data T) sneklog.LoggerWriter
 
 // BotPayloadType defines the serialization format for callback data payloads.
 type BotPayloadType string
 
-var (
+const (
 	// BotPayloadBase64 encodes callback data as a Base64 string.
 	BotPayloadBase64 BotPayloadType = "base64"
-	// BotPayloadJson encodes callback data as a JSON string.
+	// BotPayloadJSON encodes callback data as a JSON string.
-	BotPayloadJson BotPayloadType = "json"
+	BotPayloadJSON BotPayloadType = "json"
+	// BotPayloadCompact encodes callback data as a compact delimited string.
+	BotPayloadCompact BotPayloadType = "compact"
+	// BotPayloadCompactBase64 encodes compact callback data as a Base64 string.
+	BotPayloadCompactBase64 BotPayloadType = "compact-base64"
 )
 
 var (
@@ -56,7 +64,7 @@ var (
 	ErrNoPrefixes = errors.New("no prefixes defined")
 	// ErrNoPlugins reports that the bot was started without any registered plugins.
 	ErrNoPlugins = errors.New("no plugins defined")
-	// ErrBotAlreadyRun reports that Run or RunWithContext was called more than once.
+	// ErrBotAlreadyRun reports that Run, RunWithContext, or RunWebhookWithContext was called more than once.
 	ErrBotAlreadyRun = errors.New("bot can only be run once")
 
 	// ErrTokenRequired reports that BotOpts.Token was empty.
@@ -74,19 +82,28 @@ var (
 //   - Logging and rate limiting
 //   - Localization and draft message support
 //
-// Runtime accessors are safe for concurrent use. Configure the bot before Run.
+// Runtime accessors are safe for concurrent use. Configure the bot before Run,
-// A Bot is single-use: after Run or RunWithContext returns, create a new Bot for the next session.
+// RunWithContext, or RunWebhookWithContext.
-type Bot[T DbContext] struct {
+// A Bot is single-use: after Run, RunWithContext, or RunWebhookWithContext returns,
-	token         string
+// create a new Bot for the next session.
-	debug         bool
+type Bot[T AppData] struct {
-	errorTemplate string
+	token             string
-	username      string
+	debug             bool
-	payloadType   BotPayloadType
+	errorTemplate     string
-	maxWorkers    int
+	userID            int64
+	username          string
+	payloadType       BotPayloadType
+	strictPayloadType bool
+	maxWorkers        int
+	pollTimeout       int // Long-polling timeout in seconds for getUpdates
 
-	logger        *slog.Logger                // Main bot logger (JSON stdout + optional file)
+	logFormat     utils.LogFormat
-	RequestLogger *slog.Logger                // Optional request-level API logging
+	logFormatter  *sneklog.Formatter
-	extraLoggers  extypes.Slice[*slog.Logger] // API, Uploader, and custom loggers
+	logger        *sneklog.Logger // Main bot logger (JSON stdout + optional file)
+	requestLogger *sneklog.Logger // Optional request-level API logging
+	useReqLogger  bool
+	webhookLogger *sneklog.Logger                // Webhook logger. Available only after Bot.RunWebhookWithContext.
+	extraLoggers  extypes.Slice[*sneklog.Logger] // API, Uploader, and custom loggers
 
 	plugins     []Plugin[T]     // Command/event handlers
 	middlewares []Middleware[T] // Pre-processing filters (sorted by order)
@@ -95,11 +112,16 @@ type Bot[T DbContext] struct {
 
 	api           *tgapi.API      // Telegram API client
 	uploader      *tgapi.Uploader // File uploader
-	dbContext     T               // Injected database context
+	l10n          *L10n           // Localization manager
-	hasDBContext  bool
+	draftProvider *DraftProvider  // Draft message builder
-	warnedValueDB bool
+	observer      Observer        // Optional event observer for instrumentation
-	l10n          *L10n          // Localization manager
+
-	draftProvider *DraftProvider // Draft message builder
+	appData         T // Injected application data
+	hasAppData      bool
+	warnedValueData bool
+
+	sessionStore       SessionStore // Session store for scene management
+	sceneScopePriority []SceneScope
 
 	updateOffsetMu sync.Mutex
 	updateOffset   int                // Last processed update ID
@@ -112,6 +134,18 @@ type Bot[T DbContext] struct {
 	ran            bool
 }
 
+func (bot *Bot[T]) configMutable(method string) bool {
+	bot.runStateMu.Lock()
+	defer bot.runStateMu.Unlock()
+	if !bot.ran {
+		return true
+	}
+	if bot.logger != nil {
+		bot.logger.Warnln(fmt.Sprintf("%s called after bot configuration was frozen; ignoring", method))
+	}
+	return false
+}
+
 // NewBot creates and initializes a new Bot instance using the provided BotOpts.
 //
 // Automatically:
@@ -130,18 +164,30 @@ func NewBot[T any](opts *BotOpts) (*Bot[T], error) {
 
 	updateQueue := make(chan *tgapi.Update, 512)
 
-	//var limiter *utils.RateLimiter
-	//if opts.RateLimit > 0 {
-	//	limiter = utils.NewRateLimiter()
-	//}
 	limiter := utils.NewRateLimiter()
 	limiter.SetGlobalRate(opts.RateLimit)
 
+	workers := 32
+	if opts.MaxWorkers > 0 {
+		workers = opts.MaxWorkers
+	}
+
+	pollTimeout := 30
+	if opts.PollTimeout > 0 {
+		pollTimeout = opts.PollTimeout
+	}
+
+	// HTTP client timeout must exceed pollTimeout to avoid spurious deadline
+	// errors that the polling loop would misinterpret as context cancellation.
+	httpTimeout := time.Duration(pollTimeout)*time.Second + 60*time.Second
 	apiOpts := tgapi.NewAPIOpts(opts.Token).
-		SetAPIUrl(opts.APIUrl).
+		SetAPIURL(opts.APIURL).
 		UseTestServer(opts.UseTestServer).
 		SetLimiter(limiter).
-		SetLimiterDrop(opts.DropRLOverflow)
+		SetDropRateLimitOverflow(opts.DropRateLimitOverflow).
+		SetLogFormat(opts.LogFormat).
+		SetLogFormatter(opts.LogFormatter).
+		SetHTTPClient(&http.Client{Timeout: httpTimeout})
 	api := tgapi.NewAPI(apiOpts)
 	uploader := tgapi.NewUploader(api)
 
@@ -150,28 +196,32 @@ func NewBot[T any](opts *BotOpts) (*Bot[T], error) {
 		prefixes = []string{"/"}
 	}
 
-	workers := 32
-	if opts.MaxWorkers > 0 {
-		workers = opts.MaxWorkers
-	}
-
 	bot := &Bot[T]{
-		updateOffset:  0,
+		updateOffset:      0,
-		errorTemplate: "%s",
+		errorTemplate:     "%s",
-		payloadType:   BotPayloadBase64,
+		payloadType:       BotPayloadBase64,
-		maxWorkers:    workers,
+		strictPayloadType: opts.StrictPayloadType,
-		updateQueue:   updateQueue,
+		maxWorkers:        workers,
-		api:           api,
+		pollTimeout:       pollTimeout,
-		uploader:      uploader,
+		updateQueue:       updateQueue,
-		debug:         opts.Debug,
+		api:               api,
-		prefixes:      prefixes,
+		uploader:          uploader,
-		token:         opts.Token,
+		debug:             opts.Debug,
+		prefixes:          prefixes,
+		token:             opts.Token,
+		logFormat:         opts.LogFormat,
+		logFormatter:      opts.LogFormatter,
+		useReqLogger:      opts.UseRequestLogger,
+
 		plugins:       make([]Plugin[T], 0),
 		updateTypes:   append([]tgapi.UpdateType{}, opts.UpdateTypes...),
 		runners:       make([]Runner[T], 0),
-		extraLoggers:  make([]*slog.Logger, 0),
+		extraLoggers:  make([]*sneklog.Logger, 0),
 		l10n:          &L10n{},
 		draftProvider: NewRandomDraftProvider(api),
+
+		sessionStore:       NewMemorySessionStore(),
+		sceneScopePriority: []SceneScope{SceneScopeUserChat, SceneScopeChat, SceneScopeUser},
 	}
 
 	// Add API and Uploader loggers to extraLoggers for unified output
@@ -185,6 +235,16 @@ func NewBot[T any](opts *BotOpts) (*Bot[T], error) {
 	}
 	bot.initLoggers(opts)
 
+	if opts.FileConfigVersion > 0 && opts.FileConfigVersion < ConfigVersion {
+		bot.logger.Warnln(
+			fmt.Sprintf(
+				"Config file version %d is older than library version %d; please update your config file to access new features and avoid compatibility issues",
+				opts.FileConfigVersion,
+				ConfigVersion,
+			),
+		)
+	}
+
 	// Fetch bot info to validate token and get username
 	u, err := api.GetMe()
 	if err != nil {
@@ -192,51 +252,97 @@ func NewBot[T any](opts *BotOpts) (*Bot[T], error) {
 		return nil, err
 	}
 	bot.username = Val(u.Username, "")
+	bot.userID = u.ID
 	if bot.username == "" {
 		bot.logger.Warn("Can't get bot username. Named command handlers won't work!")
 	}
 	bot.logger.Infoln(fmt.Sprintf("Authorized as %s (@%s)", u.FirstName, Val(u.Username, "unknown")))
+	bot.logger.Debugln("Bot initialized with configuration:", fmt.Sprintf("%+v", opts))
 
 	return bot, nil
 }
 
+// SetLogger replaces the main bot logger.
+func (bot *Bot[T]) SetLogger(l *sneklog.Logger) *Bot[T] {
+	bot.logger = l
+	return bot
+}
+
+// SetRequestLogger replaces the request-level logger.
+func (bot *Bot[T]) SetRequestLogger(l *sneklog.Logger) *Bot[T] {
+	bot.requestLogger = l
+	return bot
+}
+
+// SetWebhookLogger replaces the webhook logger.
+func (bot *Bot[T]) SetWebhookLogger(l *sneklog.Logger) *Bot[T] {
+	bot.webhookLogger = l
+	return bot
+}
+
+// GetAPI returns the underlying Telegram Bot API client.
+func (bot *Bot[T]) GetAPI() *tgapi.API { return bot.api }
+
+// GetUploader returns the underlying file uploader client.
+func (bot *Bot[T]) GetUploader() *tgapi.Uploader { return bot.uploader }
+
 // Close gracefully shuts down bot-owned resources.
 //
 // Close shuts down, in order:
 //   - Registered plugins via Plugin.Close
+//   - Webhook logger (if initialized)
 //   - Uploader (waits for pending uploads)
 //   - API client internals
 //   - RequestLogger (if enabled)
 //   - Main logger
 //
-// RunWithContext does not call Close automatically. The caller is responsible
+// RunWithContext and RunWebhookWithContext do not call Close automatically.
-// for invoking Close after RunWithContext returns to release these resources.
+// The caller is responsible for invoking Close after runtime returns to release
+// these resources.
 //
 // Close returns a joined error containing all shutdown failures, if any.
 func (bot *Bot[T]) Close() error {
 	var e []error
+	logCloseErr := func(err error) {
+		if err == nil {
+			return
+		}
+		if bot.logger != nil {
+			bot.logger.Errorln(err)
+		}
+		e = append(e, err)
+	}
 
 	for _, p := range bot.plugins {
 		if err := p.Close(); err != nil {
 			e = append(e, err)
 		}
 	}
-	if err := bot.uploader.Close(); err != nil {
+	if bot.webhookLogger != nil {
-		bot.logger.Errorln(err)
+		if err := bot.webhookLogger.Close(); err != nil {
-		e = append(e, err)
+			logCloseErr(err)
+		}
+		bot.webhookLogger = nil
 	}
-	if err := bot.api.Close(); err != nil {
+	if bot.uploader != nil {
-		bot.logger.Errorln(err)
+		if err := bot.uploader.Close(); err != nil {
-		e = append(e, err)
+			logCloseErr(err)
-	}
-	if bot.RequestLogger != nil {
-		if err := bot.RequestLogger.Close(); err != nil {
-			bot.logger.Errorln(err)
-			e = append(e, err)
 		}
 	}
-	if err := bot.logger.Close(); err != nil {
+	if bot.api != nil {
-		e = append(e, err)
+		if err := bot.api.Close(); err != nil {
+			logCloseErr(err)
+		}
+	}
+	if bot.requestLogger != nil {
+		if err := bot.requestLogger.Close(); err != nil {
+			logCloseErr(err)
+		}
+	}
+	if bot.logger != nil {
+		if err := bot.logger.Close(); err != nil {
+			e = append(e, err)
+		}
 	}
 	return errors.Join(e...)
 }
@@ -252,38 +358,6 @@ func (bot *Bot[T]) CloseRemote(ctx context.Context) error {
 	return nil
 }
 
-// Internal logger setup for the bot and optional request logger.
-func (bot *Bot[T]) initLoggers(opts *BotOpts) {
-	level := slog.FATAL
-	if opts.Debug {
-		level = slog.DEBUG
-	}
-
-	bot.logger = utils.CreateLogger("BOT", level)
-	if opts.WriteToFile {
-		path := fmt.Sprintf("%s/main.log", strings.TrimRight(opts.LoggerBasePath, "/"))
-		logger, err := utils.CreateFileLogger("BOT", level, path)
-		if err != nil {
-			bot.logger.Errorln(err)
-		} else {
-			bot.logger = logger
-		}
-	}
-
-	if opts.UseRequestLogger {
-		bot.RequestLogger = utils.CreateLogger("REQUESTS", level)
-		if opts.WriteToFile {
-			path := fmt.Sprintf("%s/requests.log", strings.TrimRight(opts.LoggerBasePath, "/"))
-			logger, err := utils.CreateFileLogger("REQUESTS", level, path)
-			if err != nil {
-				bot.logger.Errorln(err)
-			} else {
-				bot.RequestLogger = logger
-			}
-		}
-	}
-}
-
 // GetUpdateOffset returns the current update offset (thread-safe).
 func (bot *Bot[T]) GetUpdateOffset() int {
 	bot.updateOffsetMu.Lock()
@@ -298,270 +372,31 @@ func (bot *Bot[T]) SetUpdateOffset(offset int) {
 	bot.updateOffset = offset
 }
 
-// GetUpdateTypes returns the list of update types the bot is configured to receive.
-func (bot *Bot[T]) GetUpdateTypes() []tgapi.UpdateType {
-	return append([]tgapi.UpdateType(nil), bot.updateTypes...)
-}
-
 // GetLogger returns the main bot logger.
-func (bot *Bot[T]) GetLogger() *slog.Logger { return bot.logger }
+func (bot *Bot[T]) GetLogger() *sneklog.Logger { return bot.logger }
 
-// GetDBContext returns the injected database context.
+// GetRequestLogger returns the request-level logger, if configured.
-// If DatabaseContext was not called, it returns the zero value of T.
+func (bot *Bot[T]) GetRequestLogger() *sneklog.Logger { return bot.requestLogger }
-func (bot *Bot[T]) GetDBContext() T { return bot.dbContext }
+
+// GetWebhookLogger returns the webhook logger, if configured.
+func (bot *Bot[T]) GetWebhookLogger() *sneklog.Logger { return bot.webhookLogger }
 
 // GetLoggerLevel returns the effective log level derived from the bot's debug
 // flag.
-func (bot *Bot[T]) GetLoggerLevel() slog.LogLevel {
+func (bot *Bot[T]) GetLoggerLevel() sneklog.LogLevel {
-	level := slog.FATAL
+	level := sneklog.FATAL
 	if bot.debug {
-		level = slog.DEBUG
+		level = sneklog.DEBUG
 	}
 	return level
 }
 
 // L10n translates a key in the given language.
-// Returns empty string if translation not found.
+// Returns key 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
-}
-
-// DatabaseContext injects a database context into the bot.
-// This context is accessible to plugins and middleware via GetDBContext().
-// For shared dependencies such as *sql.DB, prefer using a pointer type as T.
-// Value-typed contexts are supported, but the bot warns once because handlers
-// receive T by value.
-func (bot *Bot[T]) DatabaseContext(ctx T) *Bot[T] {
-	if !bot.warnedValueDB && shouldWarnOnValueDBContext[T]() && bot.logger != nil {
-		bot.logger.Warnln("database context uses a value type; shared dependencies should usually use a pointer type as T")
-		bot.warnedValueDB = true
-	}
-	bot.dbContext = ctx
-	bot.hasDBContext = true
-	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
-}
-
-// SetPayloadType sets the payload encoding type used for callback data.
-// JSON stores payload as a string: `{"cmd":"command","args":[...]}`.
-// Base64 stores the same JSON encoded as a Base64URL string.
-func (bot *Bot[T]) SetPayloadType(t BotPayloadType) *Bot[T] {
-	bot.payloadType = 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
-	level := slog.FATAL
-	if debug {
-		level = slog.DEBUG
-	}
-
-	bot.logger.Level(level)
-	if bot.RequestLogger != nil {
-		bot.RequestLogger.Level(level)
-	}
-	for _, p := range bot.plugins {
-		if p.logger == nil {
-			continue
-		}
-		p.logger.Level(level)
-	}
-	return bot
-}
-
-// AddPlugins registers one or more plugins.
-// Plugins are executed in registration order unless filtered by middleware.
-//
-// Registration is a commit point for plugin configuration. The Bot stores
-// plugin metadata internally, so plugins must be fully configured before they
-// are passed here. Post-registration mutation through the original *Plugin is
-// not a supported API, even if some changes appear to work due to shared maps.
-func (bot *Bot[T]) AddPlugins(plugin ...*Plugin[T]) *Bot[T] {
-	level := bot.GetLoggerLevel()
-	for _, p := range plugin {
-		if p == nil {
-			if bot.logger != nil {
-				bot.logger.Warn("nil plugin skipped")
-			}
-			continue
-		}
-		cloned := clonePlugin(p)
-		if cloned.logger == nil {
-			cloned.logger = utils.CreateLogger(cloned.name, level)
-		}
-		bot.plugins = append(bot.plugins, cloned)
-		if bot.logger != nil {
-			bot.logger.Debugln(fmt.Sprintf("plugins with name \"%s\" registered", cloned.name))
-		}
-	}
-	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)
-//
-// Middleware with an empty name are skipped with a warning.
-func (bot *Bot[T]) AddMiddleware(middleware ...Middleware[T]) *Bot[T] {
-	for _, m := range middleware {
-		if m.name == "" {
-			bot.logger.Warnln("middleware must have a non-empty name")
-			continue
-		}
-		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 {
-			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)
-//
-// Runners with an empty name are skipped with a warning.
-func (bot *Bot[T]) AddRunner(runner Runner[T]) *Bot[T] {
-	if runner.name == "" {
-		bot.logger.Warnln("runner must have a non-empty name")
-		return bot
-	}
-	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")
-		return bot
-	}
-	bot.l10n = l
-	return bot
-}
-
-// 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
-//   - Already registered plugin loggers
-//
-// Call this after AddPlugins if plugin loggers should also receive the writer.
-// Plugins registered later do not automatically inherit previously added
-// database writers; call AddDatabaseLoggerWriter again after adding them.
-//
-// Example:
-//
-//	bot.AddDatabaseLoggerWriter(func(db *MyDB) slog.LoggerWriter {
-//	    return db.QueryLogger()
-//	})
-func (bot *Bot[T]) AddDatabaseLoggerWriter(writer DbLogger[T]) *Bot[T] {
-	if !bot.hasDBContext {
-		bot.logger.Warnln("database context is not set; skipping database logger writer")
-		return bot
-	}
-	if isNilValue(bot.dbContext) {
-		bot.logger.Warnln("database context is nil; skipping database logger writer")
-		return bot
-	}
-	w := writer(bot.dbContext)
-	bot.logger.AddWriter(w)
-	if bot.RequestLogger != nil {
-		bot.RequestLogger.AddWriter(w)
-	}
-	for _, l := range bot.extraLoggers {
-		l.AddWriter(w)
-	}
-	for _, p := range bot.plugins {
-		if p.logger != nil {
-			p.logger.AddWriter(w)
-		}
-	}
-	return bot
-}
-
 // RunWithContext starts the bot with a given context for graceful shutdown.
 //
 // This is the main entry point for bot execution. It:
@@ -575,17 +410,13 @@ func (bot *Bot[T]) AddDatabaseLoggerWriter(writer DbLogger[T]) *Bot[T] {
 //   - Finishes processing currently queued updates
 //   - Waits for registered runners to exit
 //
+// If you are switching an existing deployment from webhook delivery to polling,
+// delete the current webhook first with CloseWebhook or tgapi.DeleteWebhook.
+// Telegram keeps webhook delivery active until the webhook is removed.
+//
 // RunWithContext does not close API, uploader, or logger resources on return.
 // The caller must invoke Close after RunWithContext finishes.
 //
-// Example:
-//
-//	ctx, cancel := context.WithCancel(context.Background())
-//	go bot.RunWithContext(ctx)
-//	// ... later ...
-//	cancel() // triggers graceful shutdown
-//	_ = bot.Close()
-//
 // A Bot is single-use. After RunWithContext returns, later calls return ErrBotAlreadyRun.
 func (bot *Bot[T]) RunWithContext(ctx context.Context) error {
 	if len(bot.prefixes) == 0 {
@@ -599,20 +430,46 @@ func (bot *Bot[T]) RunWithContext(ctx context.Context) error {
 		return err
 	}
 	defer bot.finishRun()
+	if !bot.useReqLogger && bot.requestLogger != nil {
+		bot.logger.Warnln("Opts#UseRequestLogger is false, but Bot#requestLogger present. Remove Bot#SetRequestLogger or set Opts#UseRequestLogger to true!")
+		err := bot.requestLogger.Close()
+		if err != nil {
+			bot.logger.Errorln(err)
+		}
+		bot.requestLogger = nil
+	}
+	if bot.webhookLogger != nil {
+		bot.logger.Warnln("Bot#webhookLogger present. You shouldn't set this, if ran in Long Polling mode!")
+		err := bot.webhookLogger.Close()
+		if err != nil {
+			bot.logger.Errorln(err)
+		}
+		bot.webhookLogger = nil
+	}
 
 	bot.ExecRunners(ctx)
 
-	bot.logger.Infoln("Bot running. Press CTRL+C to exit.")
-
 	// Start update polling in a goroutine
 	go func() {
 		defer func() {
 			if r := recover(); r != nil {
 				bot.logger.Errorln(fmt.Sprintf("panic in update polling: %v", r))
+				err, ok := r.(error)
+				if !ok {
+					err = fmt.Errorf("%v", r)
+				}
+				bot.safeEmitEvent(ctx, ErrorEvent{
+					Plugin:      "bot",
+					HandlerKind: HandlerPollingKind,
+					HandlerName: "getUpdates",
+					Err:         err,
+					UserFacing:  false,
+				})
 			}
 			close(bot.updateQueue)
 		}()
-		retryDelay := time.Duration(0)
+		backoffDelay := time.Duration(0)
+		retryCount := 0
 		for {
 			select {
 			case <-ctx.Done():
@@ -620,11 +477,31 @@ func (bot *Bot[T]) RunWithContext(ctx context.Context) error {
 			default:
 				updates, err := bot.Updates(ctx)
 				if err != nil {
-					if errors.Is(err, context.Canceled) {
+					if ctx.Err() != nil {
 						return
 					}
-					bot.logger.Errorln("failed to fetch updates:", err)
+					retryDelay, ok := pollRetryAfterDelay(err)
-					retryDelay = nextPollRetryDelay(retryDelay)
+					if ok {
+						bot.logger.Warnln("getUpdates rate limited; retrying after", retryDelay)
+						backoffDelay = 0
+					} else {
+						bot.logger.Errorln("failed to fetch updates:", err)
+						backoffDelay = nextPollRetryDelay(backoffDelay)
+						retryDelay = backoffDelay
+					}
+					retryCount++
+					bot.safeEmitEvent(ctx, PollingRetryEvent{
+						Attempt: retryCount,
+						Delay:   retryDelay,
+						Err:     err,
+					})
+					bot.safeEmitEvent(ctx, ErrorEvent{
+						Plugin:      "bot",
+						HandlerKind: HandlerPollingKind,
+						HandlerName: "getUpdates",
+						Err:         err,
+						UserFacing:  false,
+					})
 					timer := time.NewTimer(retryDelay)
 					select {
 					case <-ctx.Done():
@@ -636,13 +513,11 @@ func (bot *Bot[T]) RunWithContext(ctx context.Context) error {
 					}
 					continue
 				}
-				retryDelay = 0
+				backoffDelay = 0
+				retryCount = 0
 
 				for _, update := range updates {
-					u := update // copy loop variable to avoid race condition
+					if err := bot.enqueueUpdate(ctx, update); err != nil {
-					select {
-					case bot.updateQueue <- &u:
-					case <-ctx.Done():
 						return
 					}
 				}
@@ -650,15 +525,10 @@ func (bot *Bot[T]) RunWithContext(ctx context.Context) error {
 		}
 	}()
 
+	bot.logger.Infoln("Bot running. Press CTRL+C to exit.")
 	// Start worker pool for concurrent update handling
-	pool := pond.NewPool(bot.maxWorkers)
+	bot.startUpdateWorkers(ctx)
-	for update := range bot.updateQueue {
+
-		u := update // capture loop variable
-		pool.Submit(func() {
-			bot.handle(u)
-		})
-	}
-	pool.Stop() // Wait for all tasks to complete and stop the pool
 	bot.runnerOnceWG.Wait()
 	bot.runnerBgWG.Wait()
 	return nil
@@ -673,93 +543,3 @@ func (bot *Bot[T]) RunWithContext(ctx context.Context) error {
 func (bot *Bot[T]) Run() error {
 	return bot.RunWithContext(context.Background())
 }
-
-func (bot *Bot[T]) beginRun() error {
-	bot.runStateMu.Lock()
-	defer bot.runStateMu.Unlock()
-	if bot.running || bot.ran {
-		return ErrBotAlreadyRun
-	}
-	bot.running = true
-	bot.ran = true
-	return nil
-}
-
-func (bot *Bot[T]) finishRun() {
-	bot.runStateMu.Lock()
-	bot.running = false
-	bot.runStateMu.Unlock()
-}
-
-func nextPollRetryDelay(prev time.Duration) time.Duration {
-	if prev <= 0 {
-		return time.Second
-	}
-	next := prev * 2
-	if next > 30*time.Second {
-		return 30 * time.Second
-	}
-	return next
-}
-
-func isNilValue[T any](v T) bool {
-	rv := reflect.ValueOf(v)
-	if !rv.IsValid() {
-		return true
-	}
-	switch rv.Kind() {
-	case reflect.Chan, reflect.Func, reflect.Interface, reflect.Map, reflect.Pointer, reflect.Slice:
-		return rv.IsNil()
-	default:
-		return false
-	}
-}
-
-func shouldWarnOnValueDBContext[T any]() bool {
-	t := reflect.TypeFor[T]()
-	if t == reflect.TypeFor[NoDB]() {
-		return false
-	}
-	switch t.Kind() {
-	case reflect.Pointer, reflect.Interface, reflect.Map, reflect.Slice, reflect.Func, reflect.Chan:
-		return false
-	default:
-		return true
-	}
-}
-
-func clonePlugin[T DbContext](p *Plugin[T]) Plugin[T] {
-	cloned := Plugin[T]{
-		name:        p.name,
-		commands:    make(map[string]*Command[T], len(p.commands)),
-		payloads:    make(map[string]*Command[T], len(p.payloads)),
-		middlewares: append(extypes.Slice[Middleware[T]](nil), p.middlewares...),
-		skipAutoCmd: p.skipAutoCmd,
-		logger:      p.logger,
-		handlers:    make(map[tgapi.UpdateType]CommandExecutor[T]),
-		onClose:     p.onClose,
-	}
-
-	for name, command := range p.commands {
-		cloned.commands[name] = cloneCommand(command)
-	}
-	for name, command := range p.payloads {
-		cloned.payloads[name] = cloneCommand(command)
-	}
-	for t, handler := range p.handlers {
-		cloned.handlers[t] = handler
-	}
-
-	return cloned
-}
-
-func cloneCommand[T DbContext](command *Command[T]) *Command[T] {
-	if command == nil {
-		return nil
-	}
-
-	cloned := *command
-	cloned.args = append(extypes.Slice[CommandArg](nil), command.args...)
-	cloned.middlewares = append(extypes.Slice[Middleware[T]](nil), command.middlewares...)
-	return &cloned
-}

bot_config.go

@@ -0,0 +1,227 @@
+package laniakea
+
+import (
+	"fmt"
+	"slices"
+
+	"git.scuroneko.dev/scuroneko/laniakea/tgapi"
+	"git.scuroneko.dev/scuroneko/sneklog/v2"
+)
+
+// AddPrefixes adds one or more command prefixes (e.g., "/", "!").
+// The bot must have at least one prefix before any runtime entry point starts.
+func (bot *Bot[T]) AddPrefixes(prefixes ...string) *Bot[T] {
+	if !bot.configMutable("AddPrefixes") {
+		return bot
+	}
+	bot.prefixes = append(bot.prefixes, prefixes...)
+	return bot
+}
+
+// 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] {
+	if !bot.configMutable("SetDraftProvider") {
+		return bot
+	}
+	bot.draftProvider = p
+	return bot
+}
+
+// GetDraftProvider returns the draft provider currently used by the bot.
+func (bot *Bot[T]) GetDraftProvider() *DraftProvider {
+	return bot.draftProvider
+}
+
+// SetObserver sets an event observer for instrumentation.
+func (bot *Bot[T]) SetObserver(observer Observer) *Bot[T] {
+	if !bot.configMutable("SetObserver") {
+		return bot
+	}
+	if observer == nil {
+		if bot.logger != nil {
+			bot.logger.Warn("SetObserver called with nil observer; instrumentation will be disabled")
+		}
+		bot.observer = nil
+		return bot
+	}
+	bot.observer = observer
+	return bot
+}
+
+// GetObserver returns the bot's event observer, or nil if no observer is set.
+func (bot *Bot[T]) GetObserver() Observer {
+	return bot.observer
+}
+
+// SetSessionStore replaces the session store used for scene management.
+func (bot *Bot[T]) SetSessionStore(store SessionStore) *Bot[T] {
+	if !bot.configMutable("SetSessionStore") {
+		return bot
+	}
+	if store == nil {
+		bot.logger.Warn("SetSessionStore called with nil store; nothing changed")
+		return bot
+	}
+	bot.sessionStore = store
+	return bot
+}
+
+// GetSessionStore returns the session store used for scene management.
+func (bot *Bot[T]) GetSessionStore() SessionStore {
+	return bot.sessionStore
+}
+
+// SetSceneScopePriority sets the lookup order for resolving active scene sessions.
+func (bot *Bot[T]) SetSceneScopePriority(priority []SceneScope) *Bot[T] {
+	if !bot.configMutable("SetSceneScopePriority") {
+		return bot
+	}
+	newPriority := make([]SceneScope, 0, 3)
+	for _, scope := range priority {
+		if scope != SceneScopeUser && scope != SceneScopeChat && scope != SceneScopeUserChat {
+			bot.logger.Warnln(fmt.Sprintf("invalid scene scope %v in priority list; ignoring", scope))
+			continue
+		}
+		if slices.Index(newPriority, scope) >= 0 {
+			bot.logger.Warnln(fmt.Sprintf("duplicate scope %v in scene scope priority; ignoring duplicates", scope))
+			continue
+		}
+		newPriority = append(newPriority, scope)
+	}
+	if len(newPriority) == 0 || len(newPriority) > 3 {
+		bot.logger.Warnln("scene scope priority must have 1 to 3 scopes; ignoring invalid input")
+		return bot
+	}
+	bot.sceneScopePriority = append([]SceneScope(nil), newPriority...)
+	return bot
+}
+
+// SetAppData injects shared application data into the bot.
+//
+// The data is accessible to commands, payload handlers, middleware, scenes,
+// and runners through the generic type parameter T.
+//
+// For shared dependencies such as *sql.DB, prefer using a pointer type as T.
+// Value-typed application data is supported, but the bot warns once because
+// handlers receive T by value.
+func (bot *Bot[T]) SetAppData(ctx T) *Bot[T] {
+	if !bot.configMutable("SetAppData") {
+		return bot
+	}
+	if !bot.warnedValueData && shouldWarnOnValueAppData[T]() && bot.logger != nil {
+		bot.logger.Warnln("app data uses a value type; shared dependencies should usually use a pointer type as T")
+		bot.warnedValueData = true
+	}
+	bot.appData = ctx
+	bot.hasAppData = true
+	return bot
+}
+
+// GetAppData returns the injected application data.
+// If SetAppData was not called, it returns the zero value of T.
+func (bot *Bot[T]) GetAppData() T { return bot.appData }
+
+// SetUpdateTypes sets the list of update types the bot will request from Telegram.
+// Overwrites any previously set types.
+func (bot *Bot[T]) SetUpdateTypes(t ...tgapi.UpdateType) *Bot[T] {
+	if !bot.configMutable("SetUpdateTypes") {
+		return bot
+	}
+	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] {
+	if !bot.configMutable("AddUpdateType") {
+		return bot
+	}
+	bot.updateTypes = append(bot.updateTypes, t...)
+	return bot
+}
+
+// GetUpdateTypes returns the list of update types the bot is configured to receive.
+func (bot *Bot[T]) GetUpdateTypes() []tgapi.UpdateType {
+	return append([]tgapi.UpdateType(nil), bot.updateTypes...)
+}
+
+// SetPayloadType sets the default payload encoding type used for callback data.
+// JSON stores payload as a string: `{"cmd":"command","args":[...]}`.
+// Base64 stores the same JSON encoded as a Base64URL string.
+// InlineKeyboard.SetPayloadType may override this value for an individual keyboard.
+func (bot *Bot[T]) SetPayloadType(t BotPayloadType) *Bot[T] {
+	if !bot.configMutable("SetPayloadType") {
+		return bot
+	}
+	bot.payloadType = t
+	return bot
+}
+
+// GetPayloadType returns the bot's default callback payload encoding type.
+func (bot *Bot[T]) GetPayloadType() BotPayloadType { return bot.payloadType }
+
+// SetStrictPayloadType enables or disables strict callback payload decoding.
+// When enabled, callback payloads must match the bot's default payload type.
+func (bot *Bot[T]) SetStrictPayloadType(strict bool) *Bot[T] {
+	if !bot.configMutable("SetStrictPayloadType") {
+		return bot
+	}
+	bot.strictPayloadType = strict
+	return bot
+}
+
+// SetErrorTemplate 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]) SetErrorTemplate(s string) *Bot[T] {
+	if !bot.configMutable("SetErrorTemplate") {
+		return bot
+	}
+	bot.errorTemplate = s
+	return bot
+}
+
+// SetDebug enables or disables debug logging.
+func (bot *Bot[T]) SetDebug(debug bool) *Bot[T] {
+	if !bot.configMutable("SetDebug") {
+		return bot
+	}
+	bot.debug = debug
+	level := sneklog.FATAL
+	if debug {
+		level = sneklog.DEBUG
+	}
+
+	bot.logger.SetLevel(level)
+	if bot.requestLogger != nil {
+		bot.requestLogger.SetLevel(level)
+	}
+	for _, p := range bot.plugins {
+		if p.logger == nil {
+			continue
+		}
+		p.logger.SetLevel(level)
+	}
+	return bot
+}
+
+// SetL10n 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).
+//
+// Replaces any previously set L10n instance.
+func (bot *Bot[T]) SetL10n(l *L10n) *Bot[T] {
+	if !bot.configMutable("SetL10n") {
+		return bot
+	}
+	if l == nil {
+		bot.logger.Warn("SetL10n called with nil L10n; localization will not change")
+		return bot
+	}
+	bot.l10n = l
+	return bot
+}

bot_opts.go

@@ -5,7 +5,9 @@ import (
 	"strconv"
 	"strings"
 
-	"git.nix13.pw/scuroneko/laniakea/tgapi"
+	"git.scuroneko.dev/scuroneko/laniakea/tgapi"
+	"git.scuroneko.dev/scuroneko/laniakea/utils"
+	"git.scuroneko.dev/scuroneko/sneklog/v2"
 )
 
 // BotOpts holds configuration options for initializing a Bot.
@@ -45,19 +47,39 @@ type BotOpts struct {
 	// UseTestServer uses Telegram's test server (https://api.test.telegram.org).
 	UseTestServer bool
 
-	// APIUrl overrides the default Telegram API endpoint (useful for proxies or self-hosted).
+	// APIURL overrides the default Telegram API endpoint (useful for proxies or self-hosted).
-	APIUrl string
+	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.
+	// DropRateLimitOverflow drops incoming updates when rate limit is exceeded instead of queuing.
 	// Use this to prioritize responsiveness over reliability.
-	DropRLOverflow bool
+	DropRateLimitOverflow bool
+
+	// StrictPayloadType disables callback payload fallback decoding.
+	// When enabled, the bot accepts only the configured default payload type.
+	StrictPayloadType bool
 
 	// MaxWorkers is the maximum number of update handlers that may run concurrently.
 	MaxWorkers int
+
+	// PollTimeout is the long-polling timeout in seconds for getUpdates.
+	// Defaults to 30. Telegram allows 0..50; values outside that range are accepted
+	// by the bot but rejected by Telegram at runtime.
+	PollTimeout int
+
+	// FileConfigVersion stores the version declared by the config file used to
+	// load these options.
+	//
+	// It is zero when the options were not loaded from a versioned file.
+	FileConfigVersion int
+
+	// LogFormat selects text or JSON output for bot-managed loggers.
+	LogFormat utils.LogFormat
+	// LogFormatter customizes bot-managed logger writers when supported.
+	LogFormatter *sneklog.Formatter
 }
 
 // LoadOptsFromEnv loads BotOpts from environment variables.
@@ -75,13 +97,17 @@ type BotOpts struct {
 //   - API_URL: custom API endpoint
 //   - RATE_LIMIT: max requests per second (default: 30)
 //   - DROP_RL_OVERFLOW: "true" to drop updates on rate limit overflow
+//   - STRICT_PAYLOAD_TYPE: "true" to reject callback payloads encoded in a different format
 //   - MAX_WORKERS: maximum number of concurrent update handlers (default: 32)
+//   - POLL_TIMEOUT: long-polling timeout in seconds for getUpdates (default: 30)
+//   - LOG_FORMAT: logger output format, "text" or "json" (default: "text")
 //
 // Returns a populated BotOpts.
 // NewBot validates required fields and returns ErrTokenRequired when TG_TOKEN is missing.
 func LoadOptsFromEnv() *BotOpts {
 	rateLimit := 30
 	maxWorkers := 32
+	pollTimeout := 30
 
 	stringUpdateTypes := splitEnvList(os.Getenv("UPDATE_TYPES"))
 	updateTypes := make([]tgapi.UpdateType, 0, len(stringUpdateTypes))
@@ -96,11 +122,17 @@ func LoadOptsFromEnv() *BotOpts {
 	}
 
 	if mw := os.Getenv("MAX_WORKERS"); mw != "" {
-		if n, err := strconv.Atoi(os.Getenv("MAX_WORKERS")); err == nil {
+		if n, err := strconv.Atoi(mw); err == nil {
 			maxWorkers = n
 		}
 	}
 
+	if pt := os.Getenv("POLL_TIMEOUT"); pt != "" {
+		if n, err := strconv.Atoi(pt); err == nil {
+			pollTimeout = n
+		}
+	}
+
 	return &BotOpts{
 		Token:       os.Getenv("TG_TOKEN"),
 		UpdateTypes: updateTypes,
@@ -114,12 +146,16 @@ func LoadOptsFromEnv() *BotOpts {
 		WriteToFile:      os.Getenv("WRITE_TO_FILE") == "true",
 
 		UseTestServer: os.Getenv("USE_TEST_SERVER") == "true",
-		APIUrl:        os.Getenv("API_URL"),
+		APIURL:        os.Getenv("API_URL"),
 
-		RateLimit:      rateLimit,
+		RateLimit:             rateLimit,
-		DropRLOverflow: os.Getenv("DROP_RL_OVERFLOW") == "true",
+		DropRateLimitOverflow: os.Getenv("DROP_RL_OVERFLOW") == "true",
+		StrictPayloadType:     os.Getenv("STRICT_PAYLOAD_TYPE") == "true",
 
-		MaxWorkers: maxWorkers,
+		MaxWorkers:        maxWorkers,
+		PollTimeout:       pollTimeout,
+		FileConfigVersion: 0,
+		LogFormat:         utils.LogFormat(os.Getenv("LOG_FORMAT")),
 	}
 }
 
@@ -187,10 +223,10 @@ func (opts *BotOpts) SetUseTestServer(use bool) *BotOpts {
 	return opts
 }
 
-// SetAPIUrl overrides the default Telegram API endpoint (useful for proxies or self-hosted).
+// SetAPIURL overrides the default Telegram API endpoint (useful for proxies or self-hosted).
 // If not set, defaults to "https://api.telegram.org".
-func (opts *BotOpts) SetAPIUrl(url string) *BotOpts {
+func (opts *BotOpts) SetAPIURL(url string) *BotOpts {
-	opts.APIUrl = url
+	opts.APIURL = url
 	return opts
 }
 
@@ -201,10 +237,17 @@ func (opts *BotOpts) SetRateLimit(limit int) *BotOpts {
 	return opts
 }
 
-// SetDropRLOverflow drops incoming updates when rate limit is exceeded instead of queuing.
+// SetDropRateLimitOverflow drops incoming updates when rate limit is exceeded instead of queuing.
 // Use this to prioritize responsiveness over reliability. Default is false.
-func (opts *BotOpts) SetDropRLOverflow(drop bool) *BotOpts {
+func (opts *BotOpts) SetDropRateLimitOverflow(drop bool) *BotOpts {
-	opts.DropRLOverflow = drop
+	opts.DropRateLimitOverflow = drop
+	return opts
+}
+
+// SetStrictPayloadType enables or disables strict callback payload decoding.
+// When enabled, the bot accepts only the configured default payload type.
+func (opts *BotOpts) SetStrictPayloadType(strict bool) *BotOpts {
+	opts.StrictPayloadType = strict
 	return opts
 }
 
@@ -227,6 +270,25 @@ func (opts *BotOpts) SetMaxWorkers(workers int) *BotOpts {
 	return opts
 }
 
+// SetPollTimeout sets the long-polling timeout in seconds for getUpdates.
+// Defaults to 30. Telegram accepts 0..50.
+func (opts *BotOpts) SetPollTimeout(seconds int) *BotOpts {
+	opts.PollTimeout = seconds
+	return opts
+}
+
+// SetLogFormat sets the output format used by bot-managed loggers.
+func (opts *BotOpts) SetLogFormat(format utils.LogFormat) *BotOpts {
+	opts.LogFormat = format
+	return opts
+}
+
+// SetLogFormatter sets the formatter used by bot-managed logger writers.
+func (opts *BotOpts) SetLogFormatter(formatter *sneklog.Formatter) *BotOpts {
+	opts.LogFormatter = formatter
+	return opts
+}
+
 // LoadPrefixesFromEnv returns the PREFIXES environment variable split by semicolon.
 // Defaults to ["/"] if not set.
 func LoadPrefixesFromEnv() []string {

bot_opts_loader.go

@@ -0,0 +1,178 @@
+package laniakea
+
+import (
+	"encoding/json"
+	"fmt"
+	"io"
+	"os"
+	"regexp"
+
+	"git.scuroneko.dev/scuroneko/laniakea/tgapi"
+	"git.scuroneko.dev/scuroneko/laniakea/utils"
+)
+
+// ConfigVersion is the current version of the built-in JSON BotOpts file format.
+const ConfigVersion = 1
+
+// ErrConfigVersionMismatch reports that a config file declares a newer version
+// than this library knows how to decode.
+var ErrConfigVersionMismatch = fmt.Errorf("config version mismatch: expected %d", ConfigVersion)
+
+type botOptsFileJSONLogger struct {
+	LoggerBasePath   string          `json:"base_path"`
+	UseRequestLogger bool            `json:"use_request_logger"`
+	WriteToFile      bool            `json:"write_to_file"`
+	LogFormat        utils.LogFormat `json:"log_format"`
+}
+type botOptsFileJSONAPI struct {
+	UseTestServer  bool   `json:"use_test_server"`
+	APIURL         string `json:"url"`
+	RateLimit      int    `json:"rate_limit"`
+	PollTimeout    int    `json:"poll_timeout"`
+	DropRLOverflow bool   `json:"drop_overflow"`
+}
+
+// BotOptsFileJSON is the JSON file representation of BotOpts.
+type BotOptsFileJSON struct {
+	Version           int                   `json:"version"`
+	Token             string                `json:"token"`
+	UpdateTypes       []tgapi.UpdateType    `json:"update_types"`
+	Debug             bool                  `json:"debug"`
+	ErrorTemplate     string                `json:"error_template"`
+	Prefixes          []string              `json:"prefixes"`
+	Logger            botOptsFileJSONLogger `json:"logger"`
+	API               botOptsFileJSONAPI    `json:"api"`
+	StrictPayloadType bool                  `json:"strict_payload_type"`
+	MaxWorkers        int                   `json:"max_workers"`
+}
+
+// BotOptsFileJSONCodec encodes and decodes BotOpts using BotOptsFileJSON.
+type BotOptsFileJSONCodec struct{}
+
+// FromBytes decodes BotOpts from JSON file bytes.
+func (codec BotOptsFileJSONCodec) FromBytes(data []byte) (*BotOpts, error) {
+	fileOpts := new(BotOptsFileJSON)
+	err := json.Unmarshal(data, fileOpts)
+	if err != nil {
+		return nil, err
+	}
+	if fileOpts.Version > ConfigVersion {
+		return nil, ErrConfigVersionMismatch
+	}
+	opts := &BotOpts{
+		Token:         fileOpts.Token,
+		UpdateTypes:   fileOpts.UpdateTypes,
+		Debug:         fileOpts.Debug,
+		ErrorTemplate: fileOpts.ErrorTemplate,
+		Prefixes:      fileOpts.Prefixes,
+
+		LoggerBasePath:   fileOpts.Logger.LoggerBasePath,
+		UseRequestLogger: fileOpts.Logger.UseRequestLogger,
+		WriteToFile:      fileOpts.Logger.WriteToFile,
+		LogFormat:        fileOpts.Logger.LogFormat,
+
+		UseTestServer:         fileOpts.API.UseTestServer,
+		APIURL:                fileOpts.API.APIURL,
+		RateLimit:             fileOpts.API.RateLimit,
+		PollTimeout:           fileOpts.API.PollTimeout,
+		DropRateLimitOverflow: fileOpts.API.DropRLOverflow,
+
+		StrictPayloadType: fileOpts.StrictPayloadType,
+		MaxWorkers:        fileOpts.MaxWorkers,
+
+		FileConfigVersion: fileOpts.Version,
+	}
+	return opts, nil
+}
+
+// ToBytes encodes BotOpts into JSON file bytes.
+func (codec BotOptsFileJSONCodec) ToBytes(opts *BotOpts) ([]byte, error) {
+	fileOpts := &BotOptsFileJSON{
+		Version:       ConfigVersion,
+		Token:         opts.Token,
+		UpdateTypes:   opts.UpdateTypes,
+		Debug:         opts.Debug,
+		ErrorTemplate: opts.ErrorTemplate,
+		Prefixes:      opts.Prefixes,
+		Logger: botOptsFileJSONLogger{
+			LoggerBasePath:   opts.LoggerBasePath,
+			UseRequestLogger: opts.UseRequestLogger,
+			WriteToFile:      opts.WriteToFile,
+			LogFormat:        opts.LogFormat,
+		},
+		API: botOptsFileJSONAPI{
+			UseTestServer:  opts.UseTestServer,
+			APIURL:         opts.APIURL,
+			RateLimit:      opts.RateLimit,
+			PollTimeout:    opts.PollTimeout,
+			DropRLOverflow: opts.DropRateLimitOverflow,
+		},
+		StrictPayloadType: opts.StrictPayloadType,
+		MaxWorkers:        opts.MaxWorkers,
+	}
+	data, err := json.Marshal(fileOpts)
+	if err != nil {
+		return nil, err
+	}
+	return data, nil
+}
+
+// Load reads BotOpts from a JSON config file.
+func (codec BotOptsFileJSONCodec) Load(filename string) (*BotOpts, error) {
+	return LoadBotOptsFile(codec, filename)
+}
+
+// Save writes BotOpts to a JSON config file.
+func (codec BotOptsFileJSONCodec) Save(filename string, opts *BotOpts) error {
+	return SaveBotOptsFile(codec, filename, opts)
+}
+
+var envParameterRegex = regexp.MustCompile(`\{\{\s*(\w+)\s*\}\}`)
+
+// BotOptsFileCodec decodes and encodes BotOpts file formats.
+type BotOptsFileCodec interface {
+	FromBytes([]byte) (*BotOpts, error)
+	ToBytes(*BotOpts) ([]byte, error)
+	Load(filename string) (*BotOpts, error)
+	Save(filename string, opts *BotOpts) error
+}
+
+// LoadBotOptsFile reads a config file, expands env placeholders, and decodes BotOpts.
+func LoadBotOptsFile(codec BotOptsFileCodec, filename string) (*BotOpts, error) {
+	f, err := os.Open(filename)
+	if err != nil {
+		return nil, err
+	}
+	defer func() { _ = f.Close() }()
+	data, err := io.ReadAll(f)
+	if err != nil {
+		return nil, err
+	}
+	data = expandEnvPlaceholdersInFile(data)
+	return codec.FromBytes(data)
+}
+
+// SaveBotOptsFile encodes BotOpts with codec and writes the result to filename.
+func SaveBotOptsFile(codec BotOptsFileCodec, filename string, opts *BotOpts) error {
+	data, err := codec.ToBytes(opts)
+	if err != nil {
+		return err
+	}
+	err = os.WriteFile(filename, data, 0600)
+	if err != nil {
+		return err
+	}
+	return nil
+}
+
+func expandEnvPlaceholdersInFile(data []byte) []byte {
+	return envParameterRegex.ReplaceAllFunc(data, func(match []byte) []byte {
+		group := envParameterRegex.FindSubmatch(match)
+		if len(group) != 2 {
+			return match
+		}
+		key := group[1]
+		value := os.Getenv(string(key))
+		return []byte(value)
+	})
+}

bot_opts_loader_test.go

@@ -0,0 +1,140 @@
+package laniakea
+
+import (
+	"errors"
+	"os"
+	"path/filepath"
+	"reflect"
+	"testing"
+
+	"git.scuroneko.dev/scuroneko/laniakea/tgapi"
+)
+
+func TestBotOptsFileJSONCodecRoundTrip(t *testing.T) {
+	codec := BotOptsFileJSONCodec{}
+	want := &BotOpts{
+		Token:                 "TOKEN",
+		UpdateTypes:           []tgapi.UpdateType{tgapi.UpdateTypeMessage, tgapi.UpdateTypeCallbackQuery},
+		Debug:                 true,
+		ErrorTemplate:         "Error: %s",
+		Prefixes:              []string{"/", "!"},
+		LoggerBasePath:        "/tmp/logs",
+		UseRequestLogger:      true,
+		WriteToFile:           true,
+		UseTestServer:         true,
+		APIURL:                "https://api.example.invalid",
+		RateLimit:             42,
+		PollTimeout:           7,
+		DropRateLimitOverflow: true,
+		StrictPayloadType:     true,
+		MaxWorkers:            64,
+		FileConfigVersion:     ConfigVersion,
+	}
+
+	data, err := codec.ToBytes(want)
+	if err != nil {
+		t.Fatalf("ToBytes returned error: %v", err)
+	}
+
+	got, err := codec.FromBytes(data)
+	if err != nil {
+		t.Fatalf("FromBytes returned error: %v", err)
+	}
+
+	if !reflect.DeepEqual(got, want) {
+		t.Fatalf("round-trip mismatch:\n got: %#v\nwant: %#v", got, want)
+	}
+}
+
+func TestLoadBotOptsFileExpandsEnvPlaceholders(t *testing.T) {
+	t.Setenv("TG_TOKEN", "TOKEN_FROM_ENV")
+	t.Setenv("BOT_API_URL", "https://api.example.invalid")
+
+	dir := t.TempDir()
+	filename := filepath.Join(dir, "config.json")
+	data := []byte(`{
+		"token": "{{ TG_TOKEN }}",
+		"api": {
+			"url": "{{BOT_API_URL}}"
+		},
+		"error_template": "Error: %s"
+	}`)
+	if err := os.WriteFile(filename, data, 0o644); err != nil {
+		t.Fatalf("WriteFile returned error: %v", err)
+	}
+
+	got, err := LoadBotOptsFile(BotOptsFileJSONCodec{}, filename)
+	if err != nil {
+		t.Fatalf("LoadBotOptsFile returned error: %v", err)
+	}
+
+	if got.Token != "TOKEN_FROM_ENV" {
+		t.Fatalf("unexpected token: got %q want %q", got.Token, "TOKEN_FROM_ENV")
+	}
+	if got.APIURL != "https://api.example.invalid" {
+		t.Fatalf("unexpected api url: got %q want %q", got.APIURL, "https://api.example.invalid")
+	}
+	if got.ErrorTemplate != "Error: %s" {
+		t.Fatalf("unexpected error template: got %q", got.ErrorTemplate)
+	}
+	if got.FileConfigVersion != 0 {
+		t.Fatalf("unexpected file config version: got %d want 0", got.FileConfigVersion)
+	}
+}
+
+func TestLoadBotOptsFileReturnsDecodeError(t *testing.T) {
+	dir := t.TempDir()
+	filename := filepath.Join(dir, "config.json")
+	if err := os.WriteFile(filename, []byte(`{"token":`), 0o644); err != nil {
+		t.Fatalf("WriteFile returned error: %v", err)
+	}
+
+	if _, err := LoadBotOptsFile(BotOptsFileJSONCodec{}, filename); err == nil {
+		t.Fatal("expected decode error, got nil")
+	}
+}
+
+func TestSaveBotOptsFileWritesEncodedData(t *testing.T) {
+	dir := t.TempDir()
+	filename := filepath.Join(dir, "config.json")
+	want := &BotOpts{
+		Token:             "TOKEN",
+		UpdateTypes:       []tgapi.UpdateType{tgapi.UpdateTypeMessage},
+		ErrorTemplate:     "Error: %s",
+		Prefixes:          []string{"/"},
+		APIURL:            "https://api.example.invalid",
+		RateLimit:         30,
+		MaxWorkers:        32,
+		FileConfigVersion: ConfigVersion,
+	}
+
+	if err := SaveBotOptsFile(BotOptsFileJSONCodec{}, filename, want); err != nil {
+		t.Fatalf("SaveBotOptsFile returned error: %v", err)
+	}
+
+	got, err := LoadBotOptsFile(BotOptsFileJSONCodec{}, filename)
+	if err != nil {
+		t.Fatalf("LoadBotOptsFile returned error: %v", err)
+	}
+
+	if !reflect.DeepEqual(got, want) {
+		t.Fatalf("saved file mismatch:\n got: %#v\nwant: %#v", got, want)
+	}
+}
+
+func TestLoadBotOptsFileRejectsFutureConfigVersion(t *testing.T) {
+	dir := t.TempDir()
+	filename := filepath.Join(dir, "config.json")
+	data := []byte(`{
+		"version": 2,
+		"token": "TOKEN"
+	}`)
+	if err := os.WriteFile(filename, data, 0o644); err != nil {
+		t.Fatalf("WriteFile returned error: %v", err)
+	}
+
+	_, err := LoadBotOptsFile(BotOptsFileJSONCodec{}, filename)
+	if !errors.Is(err, ErrConfigVersionMismatch) {
+		t.Fatalf("expected ErrConfigVersionMismatch, got %v", err)
+	}
+}

bot_opts_test.go

@@ -4,7 +4,7 @@ import (
 	"reflect"
 	"testing"
 
-	"git.nix13.pw/scuroneko/laniakea/tgapi"
+	"git.scuroneko.dev/scuroneko/laniakea/tgapi"
 )
 
 func TestLoadOptsFromEnvIgnoresEmptyUpdateTypes(t *testing.T) {
@@ -45,3 +45,12 @@ func TestLoadPrefixesFromEnvDropsEmptyValues(t *testing.T) {
 		t.Fatalf("unexpected prefixes: got %v want %v", got, want)
 	}
 }
+
+func TestLoadOptsFromEnvReadsStrictPayloadType(t *testing.T) {
+	t.Setenv("STRICT_PAYLOAD_TYPE", "true")
+
+	opts := LoadOptsFromEnv()
+	if !opts.StrictPayloadType {
+		t.Fatal("expected StrictPayloadType to be enabled")
+	}
+}

bot_register.go

@@ -0,0 +1,161 @@
+package laniakea
+
+import (
+	"fmt"
+	"sort"
+
+	"git.scuroneko.dev/scuroneko/laniakea/utils"
+)
+
+// AddPlugins registers one or more plugins.
+// Plugins are executed in registration order unless filtered by middleware.
+//
+// Registration is a commit point for plugin configuration. The Bot stores
+// plugin metadata internally, so plugins must be fully configured before they
+// are passed here. Post-registration mutation through the original *Plugin is
+// not a supported API, even if some changes appear to work due to shared maps.
+func (bot *Bot[T]) AddPlugins(plugin ...*Plugin[T]) *Bot[T] {
+	if !bot.configMutable("AddPlugins") {
+		return bot
+	}
+	level := bot.GetLoggerLevel()
+	for _, p := range plugin {
+		if p == nil {
+			if bot.logger != nil {
+				bot.logger.Warn("nil plugin skipped")
+			}
+			continue
+		}
+		cloned := clonePlugin(p)
+		if cloned.logger == nil {
+			cloned.logger = utils.CreateLogger(cloned.name, level, bot.logFormat, bot.logFormatter)
+			cloned.loggerOwned = true
+		}
+		bot.addTokenReplacer(cloned.logger)
+		bot.plugins = append(bot.plugins, cloned)
+		if bot.logger != nil {
+			bot.logger.Debugln(fmt.Sprintf("plugins with name \"%s\" registered", cloned.name))
+		}
+	}
+	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)
+//
+// Middleware with an empty name are skipped with a warning.
+func (bot *Bot[T]) AddMiddleware(middleware ...Middleware[T]) *Bot[T] {
+	if !bot.configMutable("AddMiddleware") {
+		return bot
+	}
+	for _, m := range middleware {
+		if m.name == "" {
+			bot.logger.Warnln("middleware must have a non-empty name")
+			continue
+		}
+		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 {
+			return first.order < second.order
+		}
+		return first.name < second.name
+	})
+
+	return bot
+}
+
+// UsePolicy registers a Policy as a bot-level middleware.
+func (bot *Bot[T]) UsePolicy(name string, policy Policy[T]) *Bot[T] {
+	mw := RequirePolicy(name, policy)
+	return bot.AddMiddleware(mw)
+}
+
+// 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 start from the bot runtime entry points, immediately after
+// RunWithContext or RunWebhookWithContext begins.
+//
+// Example:
+//
+//	bot.AddRunner(cleanupRunner)
+//
+// Runners with an empty name are skipped with a warning.
+func (bot *Bot[T]) AddRunner(runner Runner[T]) *Bot[T] {
+	if !bot.configMutable("AddRunner") {
+		return bot
+	}
+	if runner.name == "" {
+		bot.logger.Warnln("runner must have a non-empty name")
+		return bot
+	}
+	bot.runners = append(bot.runners, runner)
+	bot.logger.Debugln(fmt.Sprintf("runner with name \"%s\" registered", runner.name))
+	return bot
+}
+
+// AddAppDataLoggerWriter adds an app-data-backed logger writer to all loggers.
+//
+// The writer will receive logs from:
+//   - Main bot logger
+//   - Request logger (if enabled)
+//   - API and Uploader loggers
+//   - Already registered plugin loggers
+//
+// Call this after AddPlugins if plugin loggers should also receive the writer.
+// Plugins registered later do not automatically inherit previously added
+// writers; call AddAppDataLoggerWriter again after adding them.
+//
+// Example:
+//
+//	bot.AddAppDataLoggerWriter(func(data *MyAppData) sneklog.LoggerWriter {
+//	    return data.QueryLogger()
+//	})
+func (bot *Bot[T]) AddAppDataLoggerWriter(writer AppDataLogger[T]) *Bot[T] {
+	if !bot.hasAppData {
+		bot.logger.Warnln("app data is not set; skipping app-data logger writer")
+		return bot
+	}
+	if isNilValue(bot.appData) {
+		bot.logger.Warnln("app data is nil; skipping app-data logger writer")
+		return bot
+	}
+	w := writer(bot.appData)
+	bot.logger.AddWriters(w)
+	if bot.requestLogger != nil {
+		bot.requestLogger.AddWriters(w)
+	}
+	for _, l := range bot.managedExtraLoggers() {
+		l.AddWriters(w)
+	}
+	for _, p := range bot.plugins {
+		if p.logger != nil {
+			p.logger.AddWriters(w)
+		}
+	}
+	bot.addTokenReplacer(bot.logger, bot.requestLogger)
+	bot.addTokenReplacer(bot.managedExtraLoggers()...)
+	return bot
+}

bot_scene.go

@@ -0,0 +1,55 @@
+package laniakea
+
+func (bot *Bot[T]) getSession(key string) (SceneSession, error) {
+	return bot.sessionStore.Get(key)
+}
+
+func (bot *Bot[T]) setSession(key string, session SceneSession) error {
+	return bot.sessionStore.Set(key, session)
+}
+
+func (bot *Bot[T]) deleteSession(key string) error {
+	return bot.sessionStore.Delete(key)
+}
+func (bot *Bot[T]) findScene(name string) (*sceneMeta, bool) {
+	for _, plugin := range bot.plugins {
+		scene, ok := plugin.scenes[name]
+		if !ok {
+			continue
+		}
+
+		steps := make(map[string]struct{}, len(scene.steps))
+		for step := range scene.steps {
+			steps[step] = struct{}{}
+		}
+
+		return &sceneMeta{
+			Name:  scene.name,
+			Scope: scene.scope,
+			Entry: scene.entry,
+			Steps: steps,
+		}, true
+	}
+	return nil, false
+}
+
+func (bot *Bot[T]) findSceneSession(ctx *MessageContext) (string, SceneSession, error) {
+	var zero SceneSession
+
+	for _, scope := range bot.sceneScopePriority {
+		key, ok := buildSceneKey(scope, ctx)
+		if !ok {
+			continue
+		}
+
+		session, err := bot.sessionStore.Get(key)
+		if err != nil {
+			return "", zero, err
+		}
+		if session.Scene != "" {
+			return key, session, nil
+		}
+	}
+
+	return "", zero, ErrCantFindSession
+}

bot_test.go

@@ -3,17 +3,53 @@ package laniakea
 import (
 	"context"
 	"errors"
+	"io"
+	"net/http"
+	"os"
 	"path/filepath"
 	"reflect"
+	"strings"
 	"testing"
 	"time"
 
-	"git.nix13.pw/scuroneko/laniakea/tgapi"
+	"git.scuroneko.dev/scuroneko/laniakea/tgapi"
-	"git.nix13.pw/scuroneko/slog"
+	"git.scuroneko.dev/scuroneko/sneklog/v2"
 )
 
+type pollingRoundTripFunc func(*http.Request) (*http.Response, error)
+
+func (f pollingRoundTripFunc) RoundTrip(req *http.Request) (*http.Response, error) {
+	return f(req)
+}
+
+type pollingRetryObserver struct {
+	recordingObserver
+	cancel      context.CancelFunc
+	cancelAfter int
+}
+
+func (o *pollingRetryObserver) OnPollingRetry(ctx context.Context, ev PollingRetryEvent) {
+	o.recordingObserver.OnPollingRetry(ctx, ev)
+	if o.cancel != nil && (o.cancelAfter == 0 || len(o.retries) >= o.cancelAfter) {
+		o.cancel()
+	}
+}
+
+type testObserver struct{}
+
+func (testObserver) OnUpdateReceived(context.Context, UpdateReceivedEvent) {}
+func (testObserver) OnUpdateHandled(context.Context, UpdateHandledEvent)   {}
+func (testObserver) OnHandlerStarted(context.Context, HandlerStartedEvent) {}
+func (testObserver) OnHandlerFinished(context.Context, HandlerFinishedEvent) {
+}
+func (testObserver) OnSceneTransition(context.Context, SceneTransitionEvent) {}
+func (testObserver) OnPolicyChecked(context.Context, PolicyCheckedEvent)     {}
+func (testObserver) OnRunnerFinished(context.Context, RunnerFinishedEvent)   {}
+func (testObserver) OnPollingRetry(context.Context, PollingRetryEvent)       {}
+func (testObserver) OnError(context.Context, ErrorEvent)                     {}
+
 func TestGetUpdateTypesReturnsCopy(t *testing.T) {
-	bot := &Bot[NoDB]{updateTypes: []tgapi.UpdateType{tgapi.UpdateTypeMessage}}
+	bot := &Bot[NoData]{updateTypes: []tgapi.UpdateType{tgapi.UpdateTypeMessage}}
 
 	got := bot.GetUpdateTypes()
 	got[0] = tgapi.UpdateTypeCallbackQuery
@@ -24,17 +60,17 @@ func TestGetUpdateTypesReturnsCopy(t *testing.T) {
 }
 
 func TestAddPluginsSnapshotsConfiguration(t *testing.T) {
-	bot := &Bot[NoDB]{logger: slog.CreateLogger()}
+	bot := &Bot[NoData]{logger: sneklog.NewLogger()}
-	plugin := NewPlugin[NoDB]("demo")
+	plugin := NewPlugin[NoData]("demo")
 
-	cmd := plugin.NewCommand(func(ctx *MsgContext, db NoDB) {}, "start")
+	cmd := plugin.Command("start", func(ctx *MessageContext, db NoData) error { return nil })
-	plugin.AddMiddleware(NewMiddleware("base", func(ctx *MsgContext, db NoDB) bool { return true }))
+	plugin.AddMiddleware(NewMiddleware("base", func(ctx *MessageContext, db NoData) bool { return true }))
 
 	bot.AddPlugins(plugin)
 
 	cmd.SetDescription("mutated after registration")
-	plugin.NewCommand(func(ctx *MsgContext, db NoDB) {}, "late")
+	plugin.Command("late", func(ctx *MessageContext, db NoData) error { return nil })
-	plugin.AddMiddleware(NewMiddleware("late", func(ctx *MsgContext, db NoDB) bool { return true }))
+	plugin.AddMiddleware(NewMiddleware("late", func(ctx *MessageContext, db NoData) bool { return true }))
 
 	registered := bot.plugins[0]
 	if _, exists := registered.commands["late"]; exists {
@@ -48,9 +84,25 @@ func TestAddPluginsSnapshotsConfiguration(t *testing.T) {
 	}
 }
 
+func TestBotPayloadTypeConfiguration(t *testing.T) {
+	bot := &Bot[NoData]{payloadType: BotPayloadBase64}
+
+	if got := bot.GetPayloadType(); got != BotPayloadBase64 {
+		t.Fatalf("unexpected initial payload type: %q", got)
+	}
+	bot.SetPayloadType(BotPayloadJSON)
+	if got := bot.GetPayloadType(); got != BotPayloadJSON {
+		t.Fatalf("unexpected updated payload type: %q", got)
+	}
+	bot.SetStrictPayloadType(true)
+	if !bot.strictPayloadType {
+		t.Fatal("expected strict payload type to be enabled")
+	}
+}
+
 func TestAddPluginsSkipsNilPlugin(t *testing.T) {
-	bot := &Bot[NoDB]{logger: slog.CreateLogger()}
+	bot := &Bot[NoData]{logger: sneklog.NewLogger()}
-	plugin := NewPlugin[NoDB]("demo")
+	plugin := NewPlugin[NoData]("demo")
 
 	bot.AddPlugins(nil, plugin)
 
@@ -63,7 +115,7 @@ func TestAddPluginsSkipsNilPlugin(t *testing.T) {
 }
 
 func TestInitLoggersFallsBackToStdoutLoggerOnFileError(t *testing.T) {
-	bot := &Bot[NoDB]{}
+	bot := &Bot[NoData]{}
 
 	bot.initLoggers(&BotOpts{
 		Debug:            true,
@@ -75,10 +127,10 @@ func TestInitLoggersFallsBackToStdoutLoggerOnFileError(t *testing.T) {
 	if bot.logger == nil {
 		t.Fatal("expected main logger fallback")
 	}
-	if bot.RequestLogger == nil {
+	if bot.requestLogger == nil {
 		t.Fatal("expected request logger fallback")
 	}
-	if err := bot.RequestLogger.Close(); err != nil {
+	if err := bot.requestLogger.Close(); err != nil {
 		t.Fatalf("failed to close request logger: %v", err)
 	}
 	if err := bot.logger.Close(); err != nil {
@@ -86,6 +138,124 @@ func TestInitLoggersFallsBackToStdoutLoggerOnFileError(t *testing.T) {
 	}
 }
 
+func TestInitLoggersAppliesTokenReplacerToFileLoggers(t *testing.T) {
+	tempDir := t.TempDir()
+	api := tgapi.NewAPI(tgapi.NewAPIOpts("secret-token"))
+	uploader := tgapi.NewUploader(api)
+	bot := &Bot[NoData]{token: "secret-token", api: api, uploader: uploader}
+	t.Cleanup(func() {
+		if err := uploader.Close(); err != nil {
+			t.Fatalf("failed to close uploader: %v", err)
+		}
+	})
+	t.Cleanup(func() {
+		if err := api.Close(); err != nil {
+			t.Fatalf("failed to close api: %v", err)
+		}
+	})
+
+	bot.initLoggers(&BotOpts{
+		Debug:            true,
+		WriteToFile:      true,
+		UseRequestLogger: true,
+		LoggerBasePath:   tempDir,
+	})
+
+	apiPath := filepath.Join(tempDir, "api.log")
+	apiFile, err := os.OpenFile(apiPath, os.O_APPEND|os.O_CREATE|os.O_WRONLY, 0644)
+	if err != nil {
+		t.Fatalf("failed to open api log: %v", err)
+	}
+	defer func() { _ = apiFile.Close() }()
+	bot.api.GetLogger().AddWriters(bot.api.GetLogger().CreateTextWriter(apiFile))
+
+	uploaderPath := filepath.Join(tempDir, "uploader.log")
+	uploaderFile, err := os.OpenFile(uploaderPath, os.O_APPEND|os.O_CREATE|os.O_WRONLY, 0644)
+	if err != nil {
+		t.Fatalf("failed to open uploader log: %v", err)
+	}
+	defer func() { _ = uploaderFile.Close() }()
+	bot.uploader.GetLogger().AddWriters(bot.uploader.GetLogger().CreateTextWriter(uploaderFile))
+
+	bot.logger.Infoln("main secret-token")
+	bot.requestLogger.Infoln("request secret-token")
+	bot.api.GetLogger().Infoln("api secret-token")
+	bot.uploader.GetLogger().Infoln("uploader secret-token")
+
+	if err := bot.requestLogger.Close(); err != nil {
+		t.Fatalf("failed to close request logger: %v", err)
+	}
+	if err := bot.logger.Close(); err != nil {
+		t.Fatalf("failed to close main logger: %v", err)
+	}
+
+	mainLog, err := os.ReadFile(filepath.Join(tempDir, "main.log"))
+	if err != nil {
+		t.Fatalf("failed to read main log: %v", err)
+	}
+	requestLog, err := os.ReadFile(filepath.Join(tempDir, "requests.log"))
+	if err != nil {
+		t.Fatalf("failed to read request log: %v", err)
+	}
+	apiLog, err := os.ReadFile(apiPath)
+	if err != nil {
+		t.Fatalf("failed to read api log: %v", err)
+	}
+	uploaderLog, err := os.ReadFile(uploaderPath)
+	if err != nil {
+		t.Fatalf("failed to read uploader log: %v", err)
+	}
+
+	for _, tt := range []struct {
+		name string
+		data string
+	}{
+		{name: "main", data: string(mainLog)},
+		{name: "request", data: string(requestLog)},
+		{name: "api", data: string(apiLog)},
+		{name: "uploader", data: string(uploaderLog)},
+	} {
+		if strings.Contains(tt.data, "secret-token") {
+			t.Fatalf("%s log leaked raw token: %q", tt.name, tt.data)
+		}
+		if !strings.Contains(tt.data, "<TOKEN>") {
+			t.Fatalf("%s log did not contain masked token: %q", tt.name, tt.data)
+		}
+	}
+}
+
+func TestAddPluginsAppliesTokenReplacerToPluginLogger(t *testing.T) {
+	bot := &Bot[NoData]{
+		token:  "secret-token",
+		logger: sneklog.NewLogger(),
+	}
+	defer func() { _ = bot.logger.Close() }()
+
+	plugin := NewPlugin[NoData]("demo")
+	bot.AddPlugins(plugin)
+
+	logPath := filepath.Join(t.TempDir(), "plugin.log")
+	file, err := os.OpenFile(logPath, os.O_APPEND|os.O_CREATE|os.O_WRONLY, 0644)
+	if err != nil {
+		t.Fatalf("failed to open plugin log: %v", err)
+	}
+	defer func() { _ = file.Close() }()
+
+	bot.plugins[0].logger.AddWriters(bot.plugins[0].logger.CreateTextWriter(file))
+	bot.plugins[0].logger.Infoln("plugin secret-token")
+
+	data, err := os.ReadFile(logPath)
+	if err != nil {
+		t.Fatalf("failed to read plugin log: %v", err)
+	}
+	if strings.Contains(string(data), "secret-token") {
+		t.Fatalf("plugin log leaked raw token: %q", string(data))
+	}
+	if !strings.Contains(string(data), "<TOKEN>") {
+		t.Fatalf("plugin log did not contain masked token: %q", string(data))
+	}
+}
+
 func TestNextPollRetryDelay(t *testing.T) {
 	tests := []struct {
 		name string
@@ -106,39 +276,39 @@ func TestNextPollRetryDelay(t *testing.T) {
 	}
 }
 
-func TestAddDatabaseLoggerWriterSkipsWhenDBContextIsUnset(t *testing.T) {
+func TestAddDatabaseLoggerWriterSkipsWhenAppDataIsUnset(t *testing.T) {
-	bot := &Bot[NoDB]{logger: slog.CreateLogger()}
+	bot := &Bot[NoData]{logger: sneklog.NewLogger()}
 	called := false
 
-	bot.AddDatabaseLoggerWriter(func(db NoDB) slog.LoggerWriter {
+	bot.AddAppDataLoggerWriter(func(db NoData) sneklog.LoggerWriter {
 		called = true
 		return nil
 	})
 
 	if called {
-		t.Fatal("expected database logger writer to be skipped when db context is unset")
+		t.Fatal("expected app-data logger writer to be skipped when app data is unset")
 	}
 }
 
-func TestAddDatabaseLoggerWriterSkipsWhenDBContextIsNil(t *testing.T) {
+func TestAddDatabaseLoggerWriterSkipsWhenAppDataIsNil(t *testing.T) {
 	type testDB struct{}
 
-	bot := &Bot[*testDB]{logger: slog.CreateLogger()}
+	bot := &Bot[*testDB]{logger: sneklog.NewLogger()}
 	var db *testDB
-	bot.DatabaseContext(db)
+	bot.SetAppData(db)
 
 	called := false
-	bot.AddDatabaseLoggerWriter(func(db *testDB) slog.LoggerWriter {
+	bot.AddAppDataLoggerWriter(func(db *testDB) sneklog.LoggerWriter {
 		called = true
 		return nil
 	})
 
 	if called {
-		t.Fatal("expected database logger writer to be skipped when db context is nil")
+		t.Fatal("expected app-data logger writer to be skipped when app data is nil")
 	}
 }
 
-func TestShouldWarnOnValueDBContext(t *testing.T) {
+func TestShouldWarnOnValueAppData(t *testing.T) {
 	type testDB struct{}
 	type dbIface interface{ Ping() error }
 
@@ -147,36 +317,64 @@ func TestShouldWarnOnValueDBContext(t *testing.T) {
 		got  bool
 		want bool
 	}{
-		{name: "NoDB", got: shouldWarnOnValueDBContext[NoDB](), want: false},
+		{name: "NoData", got: shouldWarnOnValueAppData[NoData](), want: false},
-		{name: "pointer", got: shouldWarnOnValueDBContext[*testDB](), want: false},
+		{name: "pointer", got: shouldWarnOnValueAppData[*testDB](), want: false},
-		{name: "interface", got: shouldWarnOnValueDBContext[dbIface](), want: false},
+		{name: "interface", got: shouldWarnOnValueAppData[dbIface](), want: false},
-		{name: "map", got: shouldWarnOnValueDBContext[map[string]int](), want: false},
+		{name: "map", got: shouldWarnOnValueAppData[map[string]int](), want: false},
-		{name: "struct", got: shouldWarnOnValueDBContext[testDB](), want: true},
+		{name: "struct", got: shouldWarnOnValueAppData[testDB](), want: true},
-		{name: "int", got: shouldWarnOnValueDBContext[int](), want: true},
+		{name: "int", got: shouldWarnOnValueAppData[int](), want: true},
 	}
 
 	for _, tt := range tests {
 		t.Run(tt.name, func(t *testing.T) {
 			if tt.got != tt.want {
-				t.Fatalf("shouldWarnOnValueDBContext = %v, want %v", tt.got, tt.want)
+				t.Fatalf("shouldWarnOnValueAppData = %v, want %v", tt.got, tt.want)
 			}
 		})
 	}
 }
 
-func TestDatabaseContextMarksValueWarningOnce(t *testing.T) {
+func TestSetAppDataMarksValueWarningOnce(t *testing.T) {
 	type testDB struct{}
 
-	bot := &Bot[testDB]{logger: slog.CreateLogger()}
+	bot := &Bot[testDB]{logger: sneklog.NewLogger()}
-	bot.DatabaseContext(testDB{})
+	bot.SetAppData(testDB{})
-	if !bot.warnedValueDB {
+	if !bot.warnedValueData {
-		t.Fatal("expected value-typed database context to mark warning state")
+		t.Fatal("expected value-typed app data to mark warning state")
 	}
 
-	ptrBot := &Bot[*testDB]{logger: slog.CreateLogger()}
+	ptrBot := &Bot[*testDB]{logger: sneklog.NewLogger()}
-	ptrBot.DatabaseContext(&testDB{})
+	ptrBot.SetAppData(&testDB{})
-	if ptrBot.warnedValueDB {
+	if ptrBot.warnedValueData {
-		t.Fatal("did not expect pointer-typed database context to mark warning state")
+		t.Fatal("did not expect pointer-typed app data to mark warning state")
+	}
+}
+
+func TestSetObserverAndGetObserver(t *testing.T) {
+	bot := &Bot[NoData]{logger: sneklog.NewLogger()}
+	observer := testObserver{}
+
+	if got := bot.GetObserver(); got != nil {
+		t.Fatalf("expected nil observer by default, got %#v", got)
+	}
+
+	bot.SetObserver(observer)
+	if got := bot.GetObserver(); got == nil {
+		t.Fatal("expected observer to be stored")
+	}
+}
+
+func TestSetObserverNilClearsObserver(t *testing.T) {
+	bot := &Bot[NoData]{logger: sneklog.NewLogger()}
+	bot.SetObserver(testObserver{})
+
+	if bot.GetObserver() == nil {
+		t.Fatal("expected observer to be set")
+	}
+
+	bot.SetObserver(nil)
+	if got := bot.GetObserver(); got != nil {
+		t.Fatalf("expected nil observer after clearing, got %#v", got)
 	}
 }
 
@@ -184,10 +382,10 @@ func TestRunWithContextRejectsSecondRun(t *testing.T) {
 	ctx, cancel := context.WithCancel(context.Background())
 	cancel()
 
-	bot := &Bot[NoDB]{
+	bot := &Bot[NoData]{
-		logger:      slog.CreateLogger(),
+		logger:      sneklog.NewLogger(),
 		prefixes:    []string{"/"},
-		plugins:     []Plugin[NoDB]{{name: "demo"}},
+		plugins:     []Plugin[NoData]{{name: "demo"}},
 		updateQueue: make(chan *tgapi.Update, 1),
 		maxWorkers:  1,
 	}
@@ -199,3 +397,442 @@ func TestRunWithContextRejectsSecondRun(t *testing.T) {
 		t.Fatalf("expected ErrBotAlreadyRun on second run, got %v", err)
 	}
 }
+
+func TestRunWithContextKeepsEnabledRequestLogger(t *testing.T) {
+	ctx, cancel := context.WithCancel(context.Background())
+	cancel()
+
+	requestLogger := sneklog.NewLogger()
+	bot := &Bot[NoData]{
+		logger:        sneklog.NewLogger(),
+		requestLogger: requestLogger,
+		useReqLogger:  true,
+		prefixes:      []string{"/"},
+		plugins:       []Plugin[NoData]{{name: "demo"}},
+		updateQueue:   make(chan *tgapi.Update, 1),
+		maxWorkers:    1,
+	}
+	t.Cleanup(func() {
+		_ = bot.Close()
+	})
+
+	if err := bot.RunWithContext(ctx); err != nil {
+		t.Fatalf("RunWithContext returned error: %v", err)
+	}
+	if got := bot.GetRequestLogger(); got != requestLogger {
+		t.Fatalf("expected enabled request logger to be preserved, got %#v", got)
+	}
+}
+
+func TestCloseDoesNotDeleteWebhook(t *testing.T) {
+	requests := 0
+	client := &http.Client{
+		Transport: pollingRoundTripFunc(func(req *http.Request) (*http.Response, error) {
+			requests++
+			return &http.Response{
+				StatusCode: http.StatusOK,
+				Header:     http.Header{"Content-Type": []string{"application/json"}},
+				Body:       io.NopCloser(strings.NewReader(`{"ok":true,"result":true}`)),
+			}, nil
+		}),
+	}
+
+	api := tgapi.NewAPI(
+		tgapi.NewAPIOpts("token").
+			SetAPIURL("http://example.invalid").
+			SetHTTPClient(client),
+	)
+	uploader := tgapi.NewUploader(api)
+
+	bot := &Bot[NoData]{
+		logger:        sneklog.NewLogger(),
+		webhookLogger: sneklog.NewLogger(),
+		api:           api,
+		uploader:      uploader,
+	}
+
+	if err := bot.Close(); err != nil {
+		t.Fatalf("Close returned error: %v", err)
+	}
+	if requests != 0 {
+		t.Fatalf("Close performed unexpected remote requests: got %d want 0", requests)
+	}
+}
+
+func TestRunWithContextEmitsPollingRetryAndErrorEvents(t *testing.T) {
+	ctx, cancel := context.WithCancel(context.Background())
+	defer cancel()
+	observer := &pollingRetryObserver{cancel: cancel}
+
+	client := &http.Client{
+		Transport: pollingRoundTripFunc(func(r *http.Request) (*http.Response, error) {
+			return &http.Response{
+				StatusCode: http.StatusOK,
+				Header:     http.Header{"Content-Type": []string{"application/json"}},
+				Body:       io.NopCloser(strings.NewReader(`{"ok":false,"error_code":500,"description":"boom"}`)),
+			}, nil
+		}),
+	}
+
+	api := tgapi.NewAPI(
+		tgapi.NewAPIOpts("token").
+			SetAPIURL("http://example.invalid").
+			SetHTTPClient(client),
+	)
+	defer func() {
+		_ = api.Close()
+	}()
+
+	bot := &Bot[NoData]{
+		logger:      sneklog.NewLogger(),
+		api:         api,
+		prefixes:    []string{"/"},
+		plugins:     []Plugin[NoData]{{name: "demo"}},
+		updateQueue: make(chan *tgapi.Update, 1),
+		maxWorkers:  1,
+		observer:    observer,
+	}
+
+	if err := bot.RunWithContext(ctx); err != nil {
+		t.Fatalf("RunWithContext returned error: %v", err)
+	}
+
+	if len(observer.retries) != 1 {
+		t.Fatalf("expected one polling retry event, got %d", len(observer.retries))
+	}
+	if got := observer.retries[0]; got.Attempt != 1 || got.Delay <= 0 || got.Err == nil {
+		t.Fatalf("unexpected polling retry event: %#v", got)
+	}
+	if len(observer.errors) != 1 {
+		t.Fatalf("expected one polling error event, got %d", len(observer.errors))
+	}
+	if got := observer.errors[0]; got.HandlerKind != HandlerPollingKind || got.HandlerName != "getUpdates" || got.Plugin != "bot" || got.Err == nil || got.UserFacing {
+		t.Fatalf("unexpected polling error event: %#v", got)
+	}
+}
+
+func TestRunWithContextPreservesPollingRetryBackoff(t *testing.T) {
+	ctx, cancel := context.WithCancel(context.Background())
+	defer cancel()
+	observer := &pollingRetryObserver{cancel: cancel, cancelAfter: 2}
+
+	client := &http.Client{
+		Transport: pollingRoundTripFunc(func(r *http.Request) (*http.Response, error) {
+			return &http.Response{
+				StatusCode: http.StatusOK,
+				Header:     http.Header{"Content-Type": []string{"application/json"}},
+				Body:       io.NopCloser(strings.NewReader(`{"ok":false,"error_code":500,"description":"boom"}`)),
+			}, nil
+		}),
+	}
+
+	api := tgapi.NewAPI(
+		tgapi.NewAPIOpts("token").
+			SetAPIURL("http://example.invalid").
+			SetHTTPClient(client),
+	)
+	defer func() {
+		_ = api.Close()
+	}()
+
+	bot := &Bot[NoData]{
+		logger:      sneklog.NewLogger(),
+		api:         api,
+		prefixes:    []string{"/"},
+		plugins:     []Plugin[NoData]{{name: "demo"}},
+		updateQueue: make(chan *tgapi.Update, 1),
+		maxWorkers:  1,
+		observer:    observer,
+	}
+
+	if err := bot.RunWithContext(ctx); err != nil {
+		t.Fatalf("RunWithContext returned error: %v", err)
+	}
+
+	if len(observer.retries) != 2 {
+		t.Fatalf("expected two polling retry events, got %d", len(observer.retries))
+	}
+	if got := observer.retries[0]; got.Attempt != 1 || got.Delay != time.Second {
+		t.Fatalf("unexpected first retry event: %#v", got)
+	}
+	if got := observer.retries[1]; got.Attempt != 2 || got.Delay != 2*time.Second {
+		t.Fatalf("unexpected second retry event: %#v", got)
+	}
+}
+
+func TestRunWithContextUsesTelegramRetryAfterForPollingRateLimit(t *testing.T) {
+	ctx, cancel := context.WithCancel(context.Background())
+	defer cancel()
+	observer := &pollingRetryObserver{cancel: cancel}
+
+	client := &http.Client{
+		Transport: pollingRoundTripFunc(func(r *http.Request) (*http.Response, error) {
+			return &http.Response{
+				StatusCode: http.StatusOK,
+				Header:     http.Header{"Content-Type": []string{"application/json"}},
+				Body:       io.NopCloser(strings.NewReader(`{"ok":false,"error_code":429,"description":"Too Many Requests: retry after 5","parameters":{"retry_after":5}}`)),
+			}, nil
+		}),
+	}
+
+	api := tgapi.NewAPI(
+		tgapi.NewAPIOpts("token").
+			SetAPIURL("http://example.invalid").
+			SetHTTPClient(client),
+	)
+	defer func() {
+		_ = api.Close()
+	}()
+
+	bot := &Bot[NoData]{
+		logger:      sneklog.NewLogger(),
+		api:         api,
+		prefixes:    []string{"/"},
+		plugins:     []Plugin[NoData]{{name: "demo"}},
+		updateQueue: make(chan *tgapi.Update, 1),
+		maxWorkers:  1,
+		observer:    observer,
+	}
+
+	if err := bot.RunWithContext(ctx); err != nil {
+		t.Fatalf("RunWithContext returned error: %v", err)
+	}
+
+	if len(observer.retries) != 1 {
+		t.Fatalf("expected one polling retry event, got %d", len(observer.retries))
+	}
+	if got := observer.retries[0]; got.Attempt != 1 || got.Delay != 5*time.Second {
+		t.Fatalf("unexpected polling retry event: %#v", got)
+	}
+	var responseErr *tgapi.ResponseError
+	if !errors.As(observer.retries[0].Err, &responseErr) {
+		t.Fatalf("expected ResponseError, got %T", observer.retries[0].Err)
+	}
+	if responseErr.Code != 429 || responseErr.Parameters == nil || responseErr.Parameters.RetryAfter == nil || *responseErr.Parameters.RetryAfter != 5 {
+		t.Fatalf("unexpected response error: %#v", responseErr)
+	}
+}
+
+func TestBotConfigurationFreezesAfterRunStarts(t *testing.T) {
+	type testDB struct{ Name string }
+
+	makeBot := func() *Bot[*testDB] {
+		return &Bot[*testDB]{
+			logger:             sneklog.NewLogger(),
+			prefixes:           []string{"/"},
+			updateTypes:        []tgapi.UpdateType{tgapi.UpdateTypeMessage},
+			payloadType:        BotPayloadBase64,
+			strictPayloadType:  false,
+			errorTemplate:      "%s",
+			l10n:               &L10n{},
+			draftProvider:      &DraftProvider{},
+			sessionStore:       NewMemorySessionStore(),
+			sceneScopePriority: []SceneScope{SceneScopeUserChat, SceneScopeChat, SceneScopeUser},
+		}
+	}
+
+	tests := []struct {
+		name  string
+		check func(t *testing.T, bot *Bot[*testDB])
+	}{
+		{
+			name: "SetAppData",
+			check: func(t *testing.T, bot *Bot[*testDB]) {
+				original := &testDB{Name: "before"}
+				bot.SetAppData(original)
+				if err := bot.beginRun(); err != nil {
+					t.Fatalf("beginRun returned error: %v", err)
+				}
+				t.Cleanup(bot.finishRun)
+
+				later := &testDB{Name: "after"}
+				bot.SetAppData(later)
+				if bot.appData != original {
+					t.Fatal("SetAppData mutated after configuration freeze")
+				}
+			},
+		},
+		{
+			name: "UpdateTypes",
+			check: func(t *testing.T, bot *Bot[*testDB]) {
+				original := append([]tgapi.UpdateType(nil), bot.updateTypes...)
+				if err := bot.beginRun(); err != nil {
+					t.Fatalf("beginRun returned error: %v", err)
+				}
+				t.Cleanup(bot.finishRun)
+
+				bot.SetUpdateTypes(tgapi.UpdateTypePoll)
+				if !reflect.DeepEqual(bot.updateTypes, original) {
+					t.Fatalf("UpdateTypes mutated after configuration freeze: got %v want %v", bot.updateTypes, original)
+				}
+			},
+		},
+		{
+			name: "AddUpdateType",
+			check: func(t *testing.T, bot *Bot[*testDB]) {
+				original := append([]tgapi.UpdateType(nil), bot.updateTypes...)
+				if err := bot.beginRun(); err != nil {
+					t.Fatalf("beginRun returned error: %v", err)
+				}
+				t.Cleanup(bot.finishRun)
+
+				bot.AddUpdateType(tgapi.UpdateTypePoll)
+				if !reflect.DeepEqual(bot.updateTypes, original) {
+					t.Fatalf("AddUpdateType mutated after configuration freeze: got %v want %v", bot.updateTypes, original)
+				}
+			},
+		},
+		{
+			name: "SetPayloadType",
+			check: func(t *testing.T, bot *Bot[*testDB]) {
+				if err := bot.beginRun(); err != nil {
+					t.Fatalf("beginRun returned error: %v", err)
+				}
+				t.Cleanup(bot.finishRun)
+
+				bot.SetPayloadType(BotPayloadJSON)
+				if bot.payloadType != BotPayloadBase64 {
+					t.Fatalf("payloadType mutated after configuration freeze: got %q want %q", bot.payloadType, BotPayloadBase64)
+				}
+			},
+		},
+		{
+			name: "SetStrictPayloadType",
+			check: func(t *testing.T, bot *Bot[*testDB]) {
+				if err := bot.beginRun(); err != nil {
+					t.Fatalf("beginRun returned error: %v", err)
+				}
+				t.Cleanup(bot.finishRun)
+
+				bot.SetStrictPayloadType(true)
+				if bot.strictPayloadType {
+					t.Fatal("strictPayloadType mutated after configuration freeze")
+				}
+			},
+		},
+		{
+			name: "AddPrefixes",
+			check: func(t *testing.T, bot *Bot[*testDB]) {
+				original := append([]string(nil), bot.prefixes...)
+				if err := bot.beginRun(); err != nil {
+					t.Fatalf("beginRun returned error: %v", err)
+				}
+				t.Cleanup(bot.finishRun)
+
+				bot.AddPrefixes("!")
+				if !reflect.DeepEqual(bot.prefixes, original) {
+					t.Fatalf("prefixes mutated after configuration freeze: got %v want %v", bot.prefixes, original)
+				}
+			},
+		},
+		{
+			name: "ErrorTemplate",
+			check: func(t *testing.T, bot *Bot[*testDB]) {
+				if err := bot.beginRun(); err != nil {
+					t.Fatalf("beginRun returned error: %v", err)
+				}
+				t.Cleanup(bot.finishRun)
+
+				bot.SetErrorTemplate("changed")
+				if bot.errorTemplate != "%s" {
+					t.Fatalf("errorTemplate mutated after configuration freeze: got %q want %q", bot.errorTemplate, "%s")
+				}
+			},
+		},
+		{
+			name: "SetDraftProvider",
+			check: func(t *testing.T, bot *Bot[*testDB]) {
+				original := bot.draftProvider
+				if err := bot.beginRun(); err != nil {
+					t.Fatalf("beginRun returned error: %v", err)
+				}
+				t.Cleanup(bot.finishRun)
+
+				bot.SetDraftProvider(&DraftProvider{})
+				if bot.draftProvider != original {
+					t.Fatal("draftProvider mutated after configuration freeze")
+				}
+			},
+		},
+		{
+			name: "SetSessionStore",
+			check: func(t *testing.T, bot *Bot[*testDB]) {
+				original := bot.sessionStore
+				if err := bot.beginRun(); err != nil {
+					t.Fatalf("beginRun returned error: %v", err)
+				}
+				t.Cleanup(bot.finishRun)
+
+				bot.SetSessionStore(NewMemorySessionStore())
+				if bot.sessionStore != original {
+					t.Fatal("sessionStore mutated after configuration freeze")
+				}
+			},
+		},
+		{
+			name: "SetSceneScopePriority",
+			check: func(t *testing.T, bot *Bot[*testDB]) {
+				original := append([]SceneScope(nil), bot.sceneScopePriority...)
+				if err := bot.beginRun(); err != nil {
+					t.Fatalf("beginRun returned error: %v", err)
+				}
+				t.Cleanup(bot.finishRun)
+
+				bot.SetSceneScopePriority([]SceneScope{SceneScopeUser})
+				if !reflect.DeepEqual(bot.sceneScopePriority, original) {
+					t.Fatalf("sceneScopePriority mutated after configuration freeze: got %v want %v", bot.sceneScopePriority, original)
+				}
+			},
+		},
+		{
+			name: "AddL10n",
+			check: func(t *testing.T, bot *Bot[*testDB]) {
+				original := bot.l10n
+				if err := bot.beginRun(); err != nil {
+					t.Fatalf("beginRun returned error: %v", err)
+				}
+				t.Cleanup(bot.finishRun)
+
+				bot.SetL10n(&L10n{})
+				if bot.l10n != original {
+					t.Fatal("l10n mutated after configuration freeze")
+				}
+			},
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			tt.check(t, makeBot())
+		})
+	}
+}
+
+func TestAddPluginsAndRuntimeRegistrationsNoOpAfterRunStarts(t *testing.T) {
+	bot := &Bot[NoData]{
+		logger:      sneklog.NewLogger(),
+		prefixes:    []string{"/"},
+		middlewares: []Middleware[NoData]{NewMiddleware("base", func(ctx *MessageContext, db NoData) bool { return true })},
+		runners:     []Runner[NoData]{NewRunner("base", func(bot *Bot[NoData]) error { return nil })},
+	}
+	plugin := NewPlugin[NoData]("late")
+
+	if err := bot.beginRun(); err != nil {
+		t.Fatalf("beginRun returned error: %v", err)
+	}
+	defer bot.finishRun()
+
+	bot.AddPlugins(plugin)
+	bot.AddMiddleware(NewMiddleware("late", func(ctx *MessageContext, db NoData) bool { return true }))
+	bot.AddRunner(NewRunner("late", func(bot *Bot[NoData]) error { return nil }))
+
+	if len(bot.plugins) != 0 {
+		t.Fatalf("expected AddPlugins to be ignored after configuration freeze, got %d plugins", len(bot.plugins))
+	}
+	if len(bot.middlewares) != 1 {
+		t.Fatalf("expected AddMiddleware to be ignored after configuration freeze, got %d middlewares", len(bot.middlewares))
+	}
+	if len(bot.runners) != 1 {
+		t.Fatalf("expected AddRunner to be ignored after configuration freeze, got %d runners", len(bot.runners))
+	}
+}

bot_utils.go

@@ -0,0 +1,204 @@
+package laniakea
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"maps"
+	"reflect"
+	"slices"
+	"strings"
+	"time"
+
+	"git.scuroneko.dev/scuroneko/extypes"
+	"git.scuroneko.dev/scuroneko/laniakea/tgapi"
+	"git.scuroneko.dev/scuroneko/laniakea/utils"
+
+	"git.scuroneko.dev/scuroneko/sneklog/v2"
+	"github.com/alitto/pond/v2"
+)
+
+func (bot *Bot[T]) addTokenReplacer(loggers ...*sneklog.Logger) {
+	if bot.token == "" {
+		return
+	}
+	for _, logger := range loggers {
+		if logger == nil {
+			continue
+		}
+		logger.AddReplacer(bot.token, "<TOKEN>")
+	}
+}
+
+func appendUniqueLogger(loggers []*sneklog.Logger, logger *sneklog.Logger) []*sneklog.Logger {
+	if logger == nil {
+		return loggers
+	}
+	if slices.Contains(loggers, logger) {
+		return loggers
+	}
+	return append(loggers, logger)
+}
+
+func (bot *Bot[T]) managedExtraLoggers() []*sneklog.Logger {
+	loggers := append([]*sneklog.Logger(nil), bot.extraLoggers...)
+	if bot.api != nil {
+		loggers = appendUniqueLogger(loggers, bot.api.GetLogger())
+	}
+	if bot.uploader != nil {
+		loggers = appendUniqueLogger(loggers, bot.uploader.GetLogger())
+	}
+	return loggers
+}
+
+func (bot *Bot[T]) enqueueUpdate(ctx context.Context, update tgapi.Update) error {
+	select {
+	case <-ctx.Done():
+		return ctx.Err()
+	case bot.updateQueue <- new(update):
+		return nil
+	}
+}
+
+func (bot *Bot[T]) startUpdateWorkers(ctx context.Context) {
+	pool := pond.NewPool(bot.maxWorkers)
+	for update := range bot.updateQueue {
+		u := update // capture loop variable
+		pool.Submit(func() {
+			bot.handle(ctx, u)
+		})
+	}
+	pool.StopAndWait() // Wait for all tasks to complete and stop the pool
+}
+
+func (bot *Bot[T]) initLoggers(opts *BotOpts) {
+	level := sneklog.FATAL
+	if opts.Debug {
+		level = sneklog.DEBUG
+	}
+
+	format, formatter := opts.LogFormat, opts.LogFormatter
+	if bot.logger == nil {
+		bot.logger = utils.CreateLogger("BOT", level, format, formatter)
+		if opts.WriteToFile {
+			path := fmt.Sprintf("%s/main.log", strings.TrimRight(opts.LoggerBasePath, "/"))
+			logger, err := utils.CreateFileLogger("BOT", level, path, format, formatter)
+			if err != nil {
+				bot.logger.Errorln(err)
+			} else {
+				bot.logger = logger
+			}
+		}
+	}
+
+	if opts.UseRequestLogger && bot.requestLogger == nil {
+		bot.requestLogger = utils.CreateLogger("REQUESTS", level, format, formatter)
+		if opts.WriteToFile {
+			path := fmt.Sprintf("%s/requests.log", strings.TrimRight(opts.LoggerBasePath, "/"))
+			logger, err := utils.CreateFileLogger("REQUESTS", level, path, format, formatter)
+			if err != nil {
+				bot.logger.Errorln(err)
+			} else {
+				bot.requestLogger = logger
+			}
+		}
+	}
+
+	bot.addTokenReplacer(bot.logger, bot.requestLogger)
+	bot.addTokenReplacer(bot.managedExtraLoggers()...)
+}
+
+func (bot *Bot[T]) beginRun() error {
+	bot.runStateMu.Lock()
+	defer bot.runStateMu.Unlock()
+	if bot.running || bot.ran {
+		return ErrBotAlreadyRun
+	}
+	bot.running = true
+	bot.ran = true
+	return nil
+}
+
+func (bot *Bot[T]) finishRun() {
+	bot.runStateMu.Lock()
+	bot.running = false
+	bot.runStateMu.Unlock()
+}
+
+func nextPollRetryDelay(prev time.Duration) time.Duration {
+	if prev <= 0 {
+		return time.Second
+	}
+	next := prev * 2
+	if next > 30*time.Second {
+		return 30 * time.Second
+	}
+	return next
+}
+
+func pollRetryAfterDelay(err error) (time.Duration, bool) {
+	var responseErr *tgapi.ResponseError
+	if !errors.As(err, &responseErr) || responseErr.Code != 429 || responseErr.Parameters == nil || responseErr.Parameters.RetryAfter == nil {
+		return 0, false
+	}
+	after := *responseErr.Parameters.RetryAfter
+	if after <= 0 {
+		return 0, false
+	}
+	return time.Duration(after) * time.Second, true
+}
+
+func isNilValue[T any](v T) bool {
+	rv := reflect.ValueOf(v)
+	if !rv.IsValid() {
+		return true
+	}
+	switch rv.Kind() {
+	case reflect.Chan, reflect.Func, reflect.Interface, reflect.Map, reflect.Pointer, reflect.Slice:
+		return rv.IsNil()
+	default:
+		return false
+	}
+}
+
+func shouldWarnOnValueAppData[T any]() bool {
+	t := reflect.TypeFor[T]()
+	if t == reflect.TypeFor[NoData]() {
+		return false
+	}
+	switch t.Kind() {
+	case reflect.Pointer, reflect.Interface, reflect.Map, reflect.Slice, reflect.Func, reflect.Chan:
+		return false
+	default:
+		return true
+	}
+}
+
+func clonePlugin[T AppData](p *Plugin[T]) Plugin[T] {
+	cloned := Plugin[T]{
+		name:            p.name,
+		commands:        make(map[string]*Command[T], len(p.commands)),
+		payloads:        make(map[string]*Command[T], len(p.payloads)),
+		scenes:          make(map[string]*Scene[T], len(p.scenes)),
+		middlewares:     append(extypes.Slice[Middleware[T]](nil), p.middlewares...),
+		skipAutoCmd:     p.skipAutoCmd,
+		logger:          p.logger,
+		loggerOwned:     false, // user-supplied loggers stay caller-owned; bot may take ownership during registration
+		messageFallback: p.messageFallback,
+		handlers:        make(map[tgapi.UpdateType]CommandExecutor[T]),
+		onClose:         p.onClose,
+	}
+
+	for name, command := range p.commands {
+		cloned.commands[name] = command.clone()
+	}
+	for name, command := range p.payloads {
+		cloned.payloads[name] = command.clone()
+	}
+	for name, scene := range p.scenes {
+		cloned.scenes[name] = scene.clone()
+	}
+	maps.Copy(cloned.handlers, p.handlers)
+
+	return cloned
+}

bot_webhook.go

@@ -0,0 +1,454 @@
+package laniakea
+
+import (
+	"context"
+	"crypto/subtle"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"io"
+	"net/http"
+	"os"
+	"strings"
+	"time"
+
+	"git.scuroneko.dev/scuroneko/laniakea/tgapi"
+	"git.scuroneko.dev/scuroneko/laniakea/utils"
+)
+
+// BotWebhookOpts configures Telegram webhook registration and the local HTTP server.
+type BotWebhookOpts struct {
+	Path          string
+	LocalPort     int
+	UseStatusPath bool
+
+	URL                string
+	Certificate        []byte
+	IPAddress          string
+	MaxConnections     int8
+	AllowedUpdates     []tgapi.UpdateType
+	DropPendingUpdates bool
+	SecretToken        string
+}
+
+// NewBotWebhookOpts returns webhook options with the default path, local port, and max connections.
+func NewBotWebhookOpts() *BotWebhookOpts {
+	return &BotWebhookOpts{
+		Path:           "/",
+		LocalPort:      8080,
+		MaxConnections: 40,
+	}
+}
+
+// SetPath sets the local HTTP path that receives Telegram webhook requests.
+func (opts *BotWebhookOpts) SetPath(path string) *BotWebhookOpts {
+	opts.Path = path
+	return opts
+}
+
+// SetLocalPort sets the local HTTP port used by the webhook server.
+func (opts *BotWebhookOpts) SetLocalPort(port int) *BotWebhookOpts {
+	opts.LocalPort = port
+	return opts
+}
+
+// SetUseStatusPath enables or disables the optional /status endpoint.
+// A non-empty SecretToken is required when this endpoint is enabled.
+func (opts *BotWebhookOpts) SetUseStatusPath(use bool) *BotWebhookOpts {
+	opts.UseStatusPath = use
+	return opts
+}
+
+// SetURL sets the public base URL Telegram should call for incoming updates.
+func (opts *BotWebhookOpts) SetURL(url string) *BotWebhookOpts {
+	opts.URL = url
+	return opts
+}
+
+// SetCertificate sets the self-signed webhook certificate bytes to upload.
+func (opts *BotWebhookOpts) SetCertificate(certificate []byte) *BotWebhookOpts {
+	opts.Certificate = certificate
+	return opts
+}
+
+// MustLoadCertificate loads a webhook certificate from disk and panics on failure.
+func (opts *BotWebhookOpts) MustLoadCertificate(filename string) *BotWebhookOpts {
+	f, err := os.Open(filename)
+	if err != nil {
+		panic(err)
+	}
+	defer func() {
+		_ = f.Close()
+	}()
+	opts.Certificate, err = io.ReadAll(f)
+	if err != nil {
+		panic(err)
+	}
+	return opts
+}
+
+// SetIPAddress sets the fixed IP address Telegram should use for webhook delivery.
+func (opts *BotWebhookOpts) SetIPAddress(ip string) *BotWebhookOpts {
+	opts.IPAddress = ip
+	return opts
+}
+
+// SetMaxConnections sets Telegram's maximum number of simultaneous webhook connections.
+func (opts *BotWebhookOpts) SetMaxConnections(max int8) *BotWebhookOpts {
+	opts.MaxConnections = max
+	return opts
+}
+
+// SetAllowedUpdates sets the Telegram update types that should be delivered to the webhook.
+func (opts *BotWebhookOpts) SetAllowedUpdates(updates ...tgapi.UpdateType) *BotWebhookOpts {
+	opts.AllowedUpdates = append([]tgapi.UpdateType(nil), updates...)
+	return opts
+}
+
+// SetDropPendingUpdates configures whether Telegram should drop pending updates while setting the webhook.
+func (opts *BotWebhookOpts) SetDropPendingUpdates(drop bool) *BotWebhookOpts {
+	opts.DropPendingUpdates = drop
+	return opts
+}
+
+// SetSecretToken sets the secret token expected in Telegram webhook requests.
+// The same token is also required to access /status when that endpoint is enabled.
+func (opts *BotWebhookOpts) SetSecretToken(secretToken string) *BotWebhookOpts {
+	opts.SecretToken = secretToken
+	return opts
+}
+
+// RunWebhookWithContext registers the webhook and serves incoming updates until ctx is canceled.
+//
+// The bot uses the same update queue, worker pool, runner startup, and single-use lifecycle
+// guarantees as RunWithContext. When opts.AllowedUpdates is empty, the bot-level update types
+// configured through SetUpdateTypes/AddUpdateType are used. When UseStatusPath is enabled,
+// SecretToken must be non-empty so the operational endpoint is not left public.
+//
+// When two TLS files are provided, the method serves HTTPS using the existing key-then-cert
+// argument order.
+func (bot *Bot[T]) RunWebhookWithContext(ctx context.Context, opts *BotWebhookOpts, tlsFiles ...string) error {
+	if opts == nil {
+		return ErrNilBotWebhookOpts
+	}
+	if len(bot.prefixes) == 0 {
+		return ErrNoPrefixes
+	}
+	if len(bot.plugins) == 0 {
+		return ErrNoPlugins
+	}
+	autoSecret := ""
+	if opts.SecretToken == "" {
+		rndSecret, err := generateToken(32)
+		if err != nil {
+			return err
+		}
+		opts.SecretToken = rndSecret
+		autoSecret = rndSecret
+	}
+	if opts.URL == "" {
+		return ErrNoBotWebhookOptsURL
+	}
+	if opts.MaxConnections > 100 || opts.MaxConnections <= 0 {
+		return ErrBotWebhookOptsMaxConnectionsRange
+	}
+	if err := validateWebhookPath(opts.Path, opts.UseStatusPath); err != nil {
+		return err
+	}
+	if err := validateWebhookTLSFiles(tlsFiles); err != nil {
+		return err
+	}
+
+	if opts.Certificate != nil && bot.uploader == nil {
+		return ErrBotUploaderWhenCertificate
+	}
+
+	return bot.runWebhookRuntime(ctx, func(runCtx context.Context) error {
+		if autoSecret != "" {
+			bot.webhookLogger.Warnln("Using webhook without secret is very dangerous. Using random 32 bytes token:", autoSecret)
+		}
+		i, err := bot.api.GetWebhookInfoWithContext(runCtx)
+		if err != nil {
+			return err
+		}
+		if i.URL == "" {
+			bot.webhookLogger.Warnln("API returned webhook info with empty URL. There may be a long-poll")
+		} else {
+			_, err = bot.api.DeleteWebhookWithContext(runCtx, tgapi.DeleteWebhook{})
+			if err != nil {
+				return err
+			}
+			bot.webhookLogger.Infof("Bot webhook deleted: %s", i.URL)
+		}
+
+		allowedUpdates := bot.webhookAllowedUpdates(opts)
+
+		var ok bool
+		if opts.Certificate != nil {
+			ok, err = bot.uploader.SetWebhookWithContext(runCtx, tgapi.UploadSetWebhook{
+				URL:                fmt.Sprintf("%s%s", opts.URL, opts.Path),
+				IPAddress:          opts.IPAddress,
+				MaxConnections:     opts.MaxConnections,
+				AllowedUpdates:     allowedUpdates,
+				DropPendingUpdates: opts.DropPendingUpdates,
+				SecretToken:        opts.SecretToken,
+			}, tgapi.NewUploaderFile("certificate", opts.Certificate))
+		} else {
+			ok, err = bot.api.SetWebhookWithContext(runCtx, tgapi.SetWebhook{
+				URL:                fmt.Sprintf("%s%s", opts.URL, opts.Path),
+				IPAddress:          opts.IPAddress,
+				MaxConnections:     opts.MaxConnections,
+				AllowedUpdates:     allowedUpdates,
+				DropPendingUpdates: opts.DropPendingUpdates,
+				SecretToken:        opts.SecretToken,
+			})
+		}
+		if err != nil {
+			return err
+		}
+		if !ok {
+			return ErrSetWebhookFailed
+		}
+
+		if len(tlsFiles) == 2 {
+			return bot.runWebhookTLS(runCtx, opts, tlsFiles[0], tlsFiles[1])
+		}
+
+		return bot.runWebhook(runCtx, opts)
+	})
+}
+
+// RunWebhook starts the webhook runtime with a background context.
+//
+// It is shorthand for RunWebhookWithContext(context.Background(), opts, tlsFiles...).
+func (bot *Bot[T]) RunWebhook(opts *BotWebhookOpts, tlsFiles ...string) error {
+	return bot.RunWebhookWithContext(context.Background(), opts, tlsFiles...)
+}
+
+// CloseWebhook removes the current Telegram webhook registration.
+//
+// It is separate from Close, which only releases local resources.
+// Call it before switching a deployment from webhook delivery to polling.
+func (bot *Bot[T]) CloseWebhook() error {
+	var e []error
+	if bot.api == nil {
+		e = append(e, ErrBotAPINil)
+	} else {
+		if _, err := bot.api.DeleteWebhook(tgapi.DeleteWebhook{}); err != nil {
+			if bot.webhookLogger != nil {
+				bot.webhookLogger.Errorf("Failed to close webhook: %s", err.Error())
+			} else if bot.logger != nil {
+				bot.logger.Errorf("Failed to close webhook: %s", err.Error())
+			}
+			e = append(e, err)
+		}
+	}
+	if bot.webhookLogger != nil {
+		if err := bot.webhookLogger.Close(); err != nil {
+			e = append(e, err)
+		}
+		bot.webhookLogger = nil
+	}
+	return errors.Join(e...)
+}
+
+func (bot *Bot[T]) webhookAllowedUpdates(opts *BotWebhookOpts) []tgapi.UpdateType {
+	if len(opts.AllowedUpdates) > 0 {
+		return append([]tgapi.UpdateType(nil), opts.AllowedUpdates...)
+	}
+	return bot.GetUpdateTypes()
+}
+
+func (bot *Bot[T]) runWebhookRuntime(ctx context.Context, run func(context.Context) error) error {
+	if err := bot.beginRun(); err != nil {
+		return err
+	}
+	defer bot.finishRun()
+
+	runCtx, cancel := context.WithCancel(ctx)
+	defer cancel()
+
+	if bot.webhookLogger == nil {
+		bot.webhookLogger = utils.CreateLogger("WEBHOOK", bot.GetLoggerLevel(), bot.logFormat, bot.logFormatter)
+	}
+	bot.addTokenReplacer(bot.webhookLogger)
+	bot.ExecRunners(runCtx)
+
+	workersDone := make(chan struct{})
+	go func() {
+		bot.startUpdateWorkers(runCtx)
+		close(workersDone)
+	}()
+
+	runErr := run(runCtx)
+	cancel()
+	close(bot.updateQueue)
+	<-workersDone
+	bot.runnerOnceWG.Wait()
+	bot.runnerBgWG.Wait()
+
+	return runErr
+}
+
+func updateHandler[T any](ctx context.Context, bot *Bot[T], secret []byte) http.HandlerFunc {
+	return func(w http.ResponseWriter, r *http.Request) {
+		defer func() {
+			_ = r.Body.Close()
+		}()
+		if r.Method != http.MethodPost {
+			w.WriteHeader(http.StatusMethodNotAllowed)
+			return
+		}
+		provided := []byte(r.Header.Get("X-Telegram-Bot-Api-Secret-Token"))
+
+		if len(secret) > 0 && subtle.ConstantTimeCompare(secret, provided) != 1 {
+			w.WriteHeader(http.StatusForbidden)
+			return
+		}
+
+		const maxWebhookBodySize = 256 << 10 // 256 KiB
+		r.Body = http.MaxBytesReader(w, r.Body, maxWebhookBodySize)
+
+		data, err := io.ReadAll(r.Body)
+		if err != nil {
+			if _, ok := errors.AsType[*http.MaxBytesError](err); ok {
+				w.WriteHeader(http.StatusRequestEntityTooLarge)
+				return
+			}
+			w.WriteHeader(http.StatusBadRequest)
+			return
+		}
+		if len(data) == 0 {
+			w.WriteHeader(http.StatusBadRequest)
+			return
+		}
+		var up tgapi.Update
+		if err := json.Unmarshal(data, &up); err != nil {
+			w.WriteHeader(http.StatusBadRequest)
+			bot.webhookLogger.Errorln(err)
+			return
+		}
+		bot.webhookLogger.Debugf("UPDATE id=%d type=%s size=%d from=%s", up.UpdateID, up.Type, len(data), r.RemoteAddr)
+		if err := bot.enqueueUpdate(ctx, up); err != nil {
+			bot.webhookLogger.Errorln(err)
+			w.WriteHeader(http.StatusServiceUnavailable)
+			return
+		}
+		w.WriteHeader(http.StatusOK)
+	}
+}
+
+func statusHandler[T any](bot *Bot[T], secret []byte) http.HandlerFunc {
+	return func(w http.ResponseWriter, r *http.Request) {
+		auth := ""
+		if r.Header.Get("Authorization") != "" {
+			auth = r.Header.Get("Authorization")
+		} else if r.Header.Get("X-Telegram-Bot-Api-Secret-Token") != "" {
+			auth = r.Header.Get("X-Telegram-Bot-Api-Secret-Token")
+		}
+		if len(secret) > 0 && subtle.ConstantTimeCompare(secret, []byte(auth)) != 1 {
+			w.WriteHeader(http.StatusNotFound)
+			return
+		}
+
+		i, err := bot.api.GetWebhookInfoWithContext(r.Context())
+		if err != nil {
+			bot.webhookLogger.Errorln(err)
+			w.WriteHeader(http.StatusInternalServerError)
+			return
+		}
+		data, err := json.MarshalIndent(i, "", "  ")
+		if err != nil {
+			bot.webhookLogger.Errorln(err)
+			w.WriteHeader(http.StatusInternalServerError)
+			return
+		}
+		w.Header().Set("Content-Type", "application/json")
+		if _, err := fmt.Fprint(w, string(data)); err != nil {
+			bot.webhookLogger.Errorln(err)
+		}
+	}
+}
+
+func (bot *Bot[T]) newWebhookMux(ctx context.Context, opts *BotWebhookOpts) *http.ServeMux {
+	token := []byte(opts.SecretToken)
+	r := http.NewServeMux()
+	if opts.UseStatusPath {
+		r.HandleFunc("/status", statusHandler(bot, token))
+	}
+	r.HandleFunc(opts.Path, updateHandler(ctx, bot, token))
+	return r
+}
+func (bot *Bot[T]) baseRunWebhook(ctx context.Context, opts *BotWebhookOpts, runFunc func(*http.Server, chan error)) error {
+	srv := &http.Server{
+		Addr:    fmt.Sprintf(":%d", opts.LocalPort),
+		Handler: bot.newWebhookMux(ctx, opts),
+	}
+	errCh := make(chan error, 1)
+
+	go runFunc(srv, errCh)
+
+	bot.webhookLogger.Infoln(fmt.Sprintf("Bot Webhook started at %s; waiting for updates at %s", srv.Addr, opts.URL))
+
+	select {
+	case <-ctx.Done():
+		shutdownCtx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
+		defer cancel()
+
+		if err := srv.Shutdown(shutdownCtx); err != nil {
+			return err
+		}
+
+		return <-errCh
+
+	case err := <-errCh:
+		return err
+	}
+}
+func (bot *Bot[T]) runWebhook(ctx context.Context, opts *BotWebhookOpts) error {
+	return bot.baseRunWebhook(ctx, opts, func(srv *http.Server, errCh chan error) {
+		err := srv.ListenAndServe()
+		if err != nil && !errors.Is(err, http.ErrServerClosed) {
+			errCh <- err
+			return
+		}
+		errCh <- nil
+	})
+
+}
+func (bot *Bot[T]) runWebhookTLS(ctx context.Context, opts *BotWebhookOpts, key, cert string) error {
+	return bot.baseRunWebhook(ctx, opts, func(srv *http.Server, errCh chan error) {
+		err := srv.ListenAndServeTLS(cert, key)
+		if err != nil && !errors.Is(err, http.ErrServerClosed) {
+			errCh <- err
+			return
+		}
+		errCh <- nil
+	})
+}
+func validateWebhookPath(path string, useStatusPath bool) error {
+	if path == "" {
+		return ErrBotWebhookOptsEmptyPath
+	}
+	if !strings.HasPrefix(path, "/") {
+		return ErrBotWebhookOptsPathNoSlash
+	}
+	if strings.Contains(path, "?") || strings.Contains(path, "#") {
+		return ErrBotWebhookOptsPathHasQueryOrFragment
+	}
+	if useStatusPath && path == "/status" {
+		return ErrBotWebhookOptsPathCollidesStatus
+	}
+	return nil
+}
+
+func validateWebhookTLSFiles(tlsFiles []string) error {
+	switch len(tlsFiles) {
+	case 0, 2:
+		return nil
+	case 1:
+		return ErrBotWebhookTLSFilesIncomplete
+	default:
+		return ErrBotWebhookTLSFilesTooMany
+	}
+}

bot_webhook_test.go

@@ -0,0 +1,369 @@
+package laniakea
+
+import (
+	"context"
+	"errors"
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"sync/atomic"
+	"testing"
+	"time"
+
+	"git.scuroneko.dev/scuroneko/laniakea/tgapi"
+	"git.scuroneko.dev/scuroneko/sneklog/v2"
+)
+
+func TestEnqueueUpdateCopiesValue(t *testing.T) {
+	bot := &Bot[NoData]{
+		updateQueue: make(chan *tgapi.Update, 1),
+	}
+
+	update := tgapi.Update{UpdateID: 42}
+	if err := bot.enqueueUpdate(context.Background(), update); err != nil {
+		t.Fatalf("enqueueUpdate returned error: %v", err)
+	}
+
+	update.UpdateID = 99
+
+	got := <-bot.updateQueue
+	if got.UpdateID != 42 {
+		t.Fatalf("enqueueUpdate did not copy the update value: got %d want %d", got.UpdateID, 42)
+	}
+}
+
+func TestUpdateHandlerEnqueuesUpdate(t *testing.T) {
+	bot := &Bot[NoData]{
+		updateQueue:   make(chan *tgapi.Update, 1),
+		webhookLogger: sneklog.NewLogger(),
+	}
+	t.Cleanup(func() {
+		_ = bot.webhookLogger.Close()
+	})
+
+	req := httptest.NewRequest(http.MethodPost, "/", strings.NewReader(`{"update_id":7,"message":{"message_id":1,"date":1,"chat":{"id":1,"type":"private"},"text":"/start"}}`))
+	req.Header.Set("X-Telegram-Bot-Api-Secret-Token", "secret")
+	rec := httptest.NewRecorder()
+
+	updateHandler(context.Background(), bot, []byte("secret")).ServeHTTP(rec, req)
+
+	if rec.Result().StatusCode != http.StatusOK {
+		t.Fatalf("unexpected status: got %d want %d", rec.Result().StatusCode, http.StatusOK)
+	}
+
+	select {
+	case got := <-bot.updateQueue:
+		if got.UpdateID != 7 {
+			t.Fatalf("unexpected update id in queue: got %d want %d", got.UpdateID, 7)
+		}
+		if got.Type != tgapi.UpdateTypeMessage {
+			t.Fatalf("unexpected update type in queue: got %q want %q", got.Type, tgapi.UpdateTypeMessage)
+		}
+	default:
+		t.Fatal("expected webhook handler to enqueue an update")
+	}
+}
+
+func TestRunWebhookRuntimeRejectsSecondRun(t *testing.T) {
+	bot := &Bot[NoData]{
+		logger:      sneklog.NewLogger(),
+		updateQueue: make(chan *tgapi.Update, 1),
+		maxWorkers:  1,
+	}
+	t.Cleanup(func() {
+		_ = bot.logger.Close()
+	})
+
+	if err := bot.runWebhookRuntime(context.Background(), func(context.Context) error { return nil }); err != nil {
+		t.Fatalf("first runWebhookRuntime returned error: %v", err)
+	}
+	if err := bot.runWebhookRuntime(context.Background(), func(context.Context) error { return nil }); !errors.Is(err, ErrBotAlreadyRun) {
+		t.Fatalf("expected ErrBotAlreadyRun on second run, got %v", err)
+	}
+}
+
+func TestRunWebhookRuntimeExecutesRunners(t *testing.T) {
+	var calls atomic.Int32
+
+	bot := &Bot[NoData]{
+		logger:      sneklog.NewLogger(),
+		updateQueue: make(chan *tgapi.Update, 1),
+		maxWorkers:  1,
+		runners: []Runner[NoData]{
+			NewRunner("runner", func(bot *Bot[NoData]) error {
+				calls.Add(1)
+				return nil
+			}).Async(false),
+		},
+	}
+	t.Cleanup(func() {
+		_ = bot.logger.Close()
+	})
+
+	if err := bot.runWebhookRuntime(context.Background(), func(context.Context) error { return nil }); err != nil {
+		t.Fatalf("runWebhookRuntime returned error: %v", err)
+	}
+	if got := calls.Load(); got != 1 {
+		t.Fatalf("expected runner to execute once, got %d", got)
+	}
+}
+
+func TestRunWebhookRuntimePreservesConfiguredWebhookLogger(t *testing.T) {
+	webhookLogger := sneklog.NewLogger()
+	bot := &Bot[NoData]{
+		logger:        sneklog.NewLogger(),
+		webhookLogger: webhookLogger,
+		updateQueue:   make(chan *tgapi.Update, 1),
+		maxWorkers:    1,
+	}
+	t.Cleanup(func() {
+		_ = bot.logger.Close()
+		if bot.webhookLogger != nil {
+			_ = bot.webhookLogger.Close()
+		}
+	})
+
+	if err := bot.runWebhookRuntime(context.Background(), func(context.Context) error { return nil }); err != nil {
+		t.Fatalf("runWebhookRuntime returned error: %v", err)
+	}
+	if bot.webhookLogger != webhookLogger {
+		t.Fatal("expected runWebhookRuntime to preserve configured webhook logger")
+	}
+}
+
+func TestRunWebhookRuntimeProcessesEnqueuedUpdate(t *testing.T) {
+	var calls atomic.Int32
+	plugin := NewPlugin[NoData]("demo")
+	plugin.Command("start", func(ctx *MessageContext, db NoData) error {
+		calls.Add(1)
+		return nil
+	})
+
+	bot := &Bot[NoData]{
+		logger:        sneklog.NewLogger(),
+		webhookLogger: sneklog.NewLogger(),
+		prefixes:      []string{"/"},
+		plugins:       []Plugin[NoData]{*plugin},
+		updateQueue:   make(chan *tgapi.Update, 1),
+		maxWorkers:    1,
+	}
+	t.Cleanup(func() {
+		_ = bot.logger.Close()
+		_ = bot.webhookLogger.Close()
+	})
+
+	err := bot.runWebhookRuntime(context.Background(), func(ctx context.Context) error {
+		req := httptest.NewRequest(http.MethodPost, "/", strings.NewReader(`{"update_id":9,"message":{"message_id":1,"date":1,"chat":{"id":1,"type":"private"},"from":{"id":2,"is_bot":false,"first_name":"Test"},"text":"/start"}}`))
+		rec := httptest.NewRecorder()
+
+		updateHandler(ctx, bot, []byte("")).ServeHTTP(rec, req)
+		if rec.Result().StatusCode != http.StatusOK {
+			t.Fatalf("unexpected status: got %d want %d", rec.Result().StatusCode, http.StatusOK)
+		}
+
+		deadline := time.After(time.Second)
+		for calls.Load() == 0 {
+			select {
+			case <-deadline:
+				t.Fatal("webhook runtime did not process enqueued update")
+			default:
+				time.Sleep(time.Millisecond)
+			}
+		}
+		return nil
+	})
+	if err != nil {
+		t.Fatalf("runWebhookRuntime returned error: %v", err)
+	}
+	if calls.Load() != 1 {
+		t.Fatalf("expected command handler to run once, got %d", calls.Load())
+	}
+}
+
+func TestWebhookAllowedUpdatesUsesBotUpdateTypesByDefault(t *testing.T) {
+	bot := &Bot[NoData]{
+		updateTypes: []tgapi.UpdateType{tgapi.UpdateTypeMessage, tgapi.UpdateTypeCallbackQuery},
+	}
+	opts := NewBotWebhookOpts()
+
+	got := bot.webhookAllowedUpdates(opts)
+	if len(got) != 2 {
+		t.Fatalf("unexpected allowed updates length: got %d want %d", len(got), 2)
+	}
+	if got[0] != tgapi.UpdateTypeMessage || got[1] != tgapi.UpdateTypeCallbackQuery {
+		t.Fatalf("unexpected allowed updates: %v", got)
+	}
+
+	got[0] = tgapi.UpdateTypePoll
+	if bot.updateTypes[0] != tgapi.UpdateTypeMessage {
+		t.Fatalf("webhookAllowedUpdates exposed internal slice: got %v", bot.updateTypes)
+	}
+}
+
+func TestValidateWebhookPath(t *testing.T) {
+	tests := []struct {
+		name          string
+		path          string
+		useStatusPath bool
+		wantErr       bool
+	}{
+		{name: "root", path: "/", wantErr: false},
+		{name: "custom path", path: "/telegram", wantErr: false},
+		{name: "empty", path: "", wantErr: true},
+		{name: "missing slash", path: "telegram", wantErr: true},
+		{name: "query", path: "/telegram?x=1", wantErr: true},
+		{name: "fragment", path: "/telegram#main", wantErr: true},
+		{name: "status collision", path: "/status", useStatusPath: true, wantErr: true},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			err := validateWebhookPath(tc.path, tc.useStatusPath)
+			if tc.wantErr && err == nil {
+				t.Fatal("expected error, got nil")
+			}
+			if !tc.wantErr && err != nil {
+				t.Fatalf("unexpected error: %v", err)
+			}
+		})
+	}
+}
+
+func TestValidateWebhookTLSFiles(t *testing.T) {
+	tests := []struct {
+		name    string
+		files   []string
+		wantErr bool
+	}{
+		{name: "no tls", files: nil, wantErr: false},
+		{name: "two files", files: []string{"key.pem", "cert.pem"}, wantErr: false},
+		{name: "one file", files: []string{"cert.pem"}, wantErr: true},
+		{name: "three files", files: []string{"a", "b", "c"}, wantErr: true},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			err := validateWebhookTLSFiles(tc.files)
+			if tc.wantErr && err == nil {
+				t.Fatal("expected error, got nil")
+			}
+			if !tc.wantErr && err != nil {
+				t.Fatalf("unexpected error: %v", err)
+			}
+		})
+	}
+}
+
+func TestUpdateHandlerRejectsOversizedBody(t *testing.T) {
+	bot := &Bot[NoData]{
+		updateQueue:   make(chan *tgapi.Update, 1),
+		webhookLogger: sneklog.NewLogger(),
+	}
+	t.Cleanup(func() {
+		_ = bot.webhookLogger.Close()
+	})
+
+	req := httptest.NewRequest(http.MethodPost, "/", strings.NewReader(strings.Repeat("a", (256<<10)+1)))
+	rec := httptest.NewRecorder()
+
+	updateHandler(context.Background(), bot, []byte("")).ServeHTTP(rec, req)
+
+	if rec.Result().StatusCode != http.StatusRequestEntityTooLarge {
+		t.Fatalf("unexpected status: got %d want %d", rec.Result().StatusCode, http.StatusRequestEntityTooLarge)
+	}
+}
+
+func TestStatusHandlerRequiresMatchingSecret(t *testing.T) {
+	client := &http.Client{
+		Transport: pollingRoundTripFunc(func(req *http.Request) (*http.Response, error) {
+			return &http.Response{
+				StatusCode: http.StatusOK,
+				Header:     http.Header{"Content-Type": []string{"application/json"}},
+				Body:       io.NopCloser(strings.NewReader(`{"ok":true,"result":{"url":"https://bot.example.com/telegram"}}`)),
+			}, nil
+		}),
+	}
+	api := tgapi.NewAPI(
+		tgapi.NewAPIOpts("token").
+			SetAPIURL("http://example.invalid").
+			SetHTTPClient(client),
+	)
+	defer func() {
+		_ = api.Close()
+	}()
+
+	bot := &Bot[NoData]{
+		api:           api,
+		webhookLogger: sneklog.NewLogger(),
+	}
+	t.Cleanup(func() {
+		_ = bot.webhookLogger.Close()
+	})
+
+	handler := statusHandler(bot, []byte("secret"))
+
+	tests := []struct {
+		name       string
+		headerName string
+		headerVal  string
+		wantStatus int
+	}{
+		{name: "missing auth", wantStatus: http.StatusNotFound},
+		{name: "wrong auth", headerName: "Authorization", headerVal: "wrong", wantStatus: http.StatusNotFound},
+		{name: "matching length wrong content", headerName: "X-Telegram-Bot-Api-Secret-Token", headerVal: "secres", wantStatus: http.StatusNotFound},
+		{name: "shared prefix shorter", headerName: "X-Telegram-Bot-Api-Secret-Token", headerVal: "secre", wantStatus: http.StatusNotFound},
+		{name: "shared prefix longer", headerName: "X-Telegram-Bot-Api-Secret-Token", headerVal: "secretxx", wantStatus: http.StatusNotFound},
+		{name: "matching telegram header", headerName: "X-Telegram-Bot-Api-Secret-Token", headerVal: "secret", wantStatus: http.StatusOK},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			req := httptest.NewRequest(http.MethodGet, "/status", nil)
+			if tc.headerName != "" {
+				req.Header.Set(tc.headerName, tc.headerVal)
+			}
+			rec := httptest.NewRecorder()
+
+			handler.ServeHTTP(rec, req)
+
+			if rec.Result().StatusCode != tc.wantStatus {
+				t.Fatalf("unexpected status: got %d want %d", rec.Result().StatusCode, tc.wantStatus)
+			}
+		})
+	}
+}
+
+func TestRunWebhookWithContextRejectsInvalidTLSFilesBeforeRemoteSetup(t *testing.T) {
+	bot := &Bot[NoData]{
+		prefixes: []string{"/"},
+		plugins:  []Plugin[NoData]{{name: "demo"}},
+	}
+	opts := NewBotWebhookOpts().SetURL("https://bot.example.com")
+
+	err := bot.RunWebhookWithContext(context.Background(), opts, "cert.pem")
+	if err == nil {
+		t.Fatal("expected tls validation error, got nil")
+	}
+	if !strings.Contains(err.Error(), "both private and public keys") {
+		t.Fatalf("unexpected error: %v", err)
+	}
+}
+
+func TestRunWebhookWithContextAutoGeneratesSecretWhenEmpty(t *testing.T) {
+	bot := &Bot[NoData]{
+		prefixes: []string{"/"},
+		plugins:  []Plugin[NoData]{{name: "demo"}},
+	}
+	// No SecretToken, no URL — function should auto-generate the token
+	// and then fail with ErrNoBotWebhookOptsURL before any network call.
+	opts := NewBotWebhookOpts().SetUseStatusPath(true)
+
+	err := bot.RunWebhookWithContext(context.Background(), opts)
+	if !errors.Is(err, ErrNoBotWebhookOptsURL) {
+		t.Fatalf("expected ErrNoBotWebhookOptsURL after auto-generation, got: %v", err)
+	}
+	if opts.SecretToken == "" {
+		t.Fatal("expected SecretToken to be auto-generated, got empty string")
+	}
+}

cmd_generator.go

@@ -7,11 +7,11 @@ import (
 	"sort"
 	"strings"
 
-	"git.nix13.pw/scuroneko/laniakea/tgapi"
+	"git.scuroneko.dev/scuroneko/laniakea/tgapi"
 )
 
-// CmdRegexp matches command names allowed for Telegram command registration.
+// cmdRegexp matches command names allowed for Telegram command registration.
-var CmdRegexp = regexp.MustCompile("^[_a-z0-9]{1,32}$")
+var cmdRegexp = regexp.MustCompile("^[_a-z0-9]{1,32}$")
 
 // ErrTooManyCommands is returned when the total number of registered commands
 // exceeds Telegram's limit of 100 bot commands per bot.
@@ -21,7 +21,6 @@ var CmdRegexp = regexp.MustCompile("^[_a-z0-9]{1,32}$")
 // bot initialization.
 var ErrTooManyCommands = errors.New("too many commands. max 100")
 
-// Internal helper to build a BotCommand description with generated usage text.
 func generateBotCommand[T any](cmd *Command[T]) tgapi.BotCommand {
 	desc := ""
 	if len(cmd.description) > 0 {
@@ -45,10 +44,8 @@ func generateBotCommand[T any](cmd *Command[T]) tgapi.BotCommand {
 	return tgapi.BotCommand{Command: cmd.command, Description: usage}
 }
 
-// Internal helper to validate Telegram command names.
+func checkCmdRegex(cmd string) bool { return cmdRegexp.MatchString(cmd) }
-func checkCmdRegex(cmd string) bool { return CmdRegexp.MatchString(cmd) }
 
-// Internal helper to collect non-skipped, valid commands from one plugin.
 func gatherCommandsForPlugin[T any](pl Plugin[T]) []tgapi.BotCommand {
 	commands := make([]tgapi.BotCommand, 0)
 	names := make([]string, 0, len(pl.commands))
@@ -70,7 +67,6 @@ func gatherCommandsForPlugin[T any](pl Plugin[T]) []tgapi.BotCommand {
 	return commands
 }
 
-// Internal helper to collect all auto-generated commands from registered plugins.
 func gatherCommands[T any](bot *Bot[T]) []tgapi.BotCommand {
 	commands := make([]tgapi.BotCommand, 0)
 	for _, pl := range bot.plugins {
@@ -112,7 +108,7 @@ func (bot *Bot[T]) AutoGenerateCommands() error {
 	}
 
 	// Clear existing commands to avoid duplication or stale entries
-	_, err := bot.api.DeleteMyCommands(tgapi.DeleteMyCommandsP{})
+	_, err := bot.api.DeleteMyCommands(tgapi.DeleteMyCommands{})
 	if err != nil {
 		return fmt.Errorf("failed to delete existing commands: %w", err)
 	}
@@ -125,7 +121,7 @@ func (bot *Bot[T]) AutoGenerateCommands() error {
 	}
 
 	for _, scope := range scopes {
-		_, err = bot.api.SetMyCommands(tgapi.SetMyCommandsP{
+		_, err = bot.api.SetMyCommands(tgapi.SetMyCommands{
 			Commands: commands,
 			Scope:    scope,
 		})
@@ -159,12 +155,12 @@ func (bot *Bot[T]) AutoGenerateCommandsForScope(scope *tgapi.BotCommandScope) er
 		return ErrTooManyCommands
 	}
 
-	_, err := bot.api.DeleteMyCommands(tgapi.DeleteMyCommandsP{Scope: scope})
+	_, err := bot.api.DeleteMyCommands(tgapi.DeleteMyCommands{Scope: scope})
 	if err != nil {
 		return fmt.Errorf("failed to delete existing commands: %w", err)
 	}
 
-	_, err = bot.api.SetMyCommands(tgapi.SetMyCommandsP{
+	_, err = bot.api.SetMyCommands(tgapi.SetMyCommands{
 		Commands: commands,
 		Scope:    scope,
 	})

cmd_generator_test.go

@@ -10,8 +10,8 @@ import (
 	"sync/atomic"
 	"testing"
 
-	"git.nix13.pw/scuroneko/laniakea/tgapi"
+	"git.scuroneko.dev/scuroneko/laniakea/tgapi"
-	"git.nix13.pw/scuroneko/slog"
+	"git.scuroneko.dev/scuroneko/sneklog/v2"
 )
 
 type roundTripFunc func(*http.Request) (*http.Response, error)
@@ -34,7 +34,7 @@ func TestAutoGenerateCommandsChecksLimitBeforeDelete(t *testing.T) {
 	}
 	api := tgapi.NewAPI(
 		tgapi.NewAPIOpts("token").
-			SetAPIUrl("https://example.test").
+			SetAPIURL("https://example.test").
 			SetHTTPClient(client),
 	)
 	defer func() {
@@ -43,16 +43,16 @@ func TestAutoGenerateCommandsChecksLimitBeforeDelete(t *testing.T) {
 		}
 	}()
 
-	plugin := NewPlugin[NoDB]("overflow")
+	plugin := NewPlugin[NoData]("overflow")
-	exec := func(ctx *MsgContext, db NoDB) {}
+	exec := func(ctx *MessageContext, db NoData) error { return nil }
 	for i := 0; i < 101; i++ {
-		plugin.AddCommand(NewCommand(exec, "cmd"+strconv.Itoa(i)))
+		plugin.Command("cmd"+strconv.Itoa(i), exec)
 	}
 
-	bot := &Bot[NoDB]{
+	bot := &Bot[NoData]{
 		api:     api,
-		logger:  slog.CreateLogger(),
+		logger:  sneklog.NewLogger(),
-		plugins: []Plugin[NoDB]{*plugin},
+		plugins: []Plugin[NoData]{*plugin},
 	}
 
 	err := bot.AutoGenerateCommands()
@@ -65,12 +65,12 @@ func TestAutoGenerateCommandsChecksLimitBeforeDelete(t *testing.T) {
 }
 
 func TestGatherCommandsForPluginReturnsSortedCommands(t *testing.T) {
-	plugin := NewPlugin[NoDB]("sorted")
+	plugin := NewPlugin[NoData]("sorted")
-	exec := func(ctx *MsgContext, db NoDB) {}
+	exec := func(ctx *MessageContext, db NoData) error { return nil }
 
-	plugin.AddCommand(NewCommand(exec, "zeta"))
+	plugin.Command("zeta", exec)
-	plugin.AddCommand(NewCommand(exec, "alpha"))
+	plugin.Command("alpha", exec)
-	plugin.AddCommand(NewCommand(exec, "mid"))
+	plugin.Command("mid", exec)
 
 	commands := gatherCommandsForPlugin(*plugin)
 	got := make([]string, 0, len(commands))

commands.go

@@ -0,0 +1,214 @@
+package laniakea
+
+import (
+	"errors"
+	"regexp"
+
+	"git.scuroneko.dev/scuroneko/extypes"
+)
+
+// CommandValueType defines the expected type of command argument.
+type CommandValueType string
+
+const (
+	// CommandValueString expects any non-empty string.
+	CommandValueString CommandValueType = "string"
+	// CommandValueInt expects a decimal integer (digits only).
+	CommandValueInt CommandValueType = "int"
+	// CommandValueBool expects an exact "true" or "false".
+	CommandValueBool CommandValueType = "bool"
+	// CommandValueAny accepts any input without validation.
+	CommandValueAny CommandValueType = "any"
+)
+
+var (
+	// CommandRegexInt matches one or more digits.
+	CommandRegexInt = regexp.MustCompile(`^\d+$`)
+	// CommandRegexString matches any non-empty string.
+	CommandRegexString = regexp.MustCompile(`^.+$`)
+	// CommandRegexBool matches true or false.
+	CommandRegexBool = regexp.MustCompile(`^(true|false)$`)
+)
+
+// 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")
+
+var (
+	errCommandNotFound = errors.New("command not found")
+	errPayloadNotFound = errors.New("payload not found")
+)
+
+// CommandArg defines a single argument for a command, including type, regex,
+// and whether it is required.
+type CommandArg struct {
+	valueType CommandValueType // Type of expected value
+	text      string           // Human-readable description (not used in validation)
+	regex     *regexp.Regexp   // Regex used to validate input
+	required  bool             // Whether this argument must be provided
+}
+
+// NewCommandArg creates an optional argument without value validation.
+func NewCommandArg(text string) CommandArg {
+	return CommandArg{CommandValueAny, text, nil, false}
+}
+
+// SetValueType sets expected value type and switches built-in validation regexp.
+func (c CommandArg) SetValueType(t CommandValueType) CommandArg {
+	var regex *regexp.Regexp
+	switch t {
+	case CommandValueInt:
+		regex = CommandRegexInt
+	case CommandValueBool:
+		regex = CommandRegexBool
+	case CommandValueString:
+		regex = CommandRegexString
+	}
+	c.valueType = t
+	c.regex = regex
+	return c
+}
+
+// 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 injected application data.
+// Returning a non-nil error routes it through the bot's error handler.
+type CommandExecutor[T AppData] func(ctx *MessageContext, dbContext T) error
+
+// 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 AppData] struct {
+	command     string                       // The command trigger (e.g., "/start")
+	description string                       // Human-readable description for help
+	exec        CommandExecutor[T]           // Function to execute when command is triggered
+	args        extypes.Slice[CommandArg]    // List of expected arguments
+	middlewares extypes.Slice[Middleware[T]] // Optional middleware chain
+	skipAutoCmd bool                         // If true, this command won't be auto-added to help menus
+}
+
+// NewCommand creates a new Command with the given identifier, executor, and arguments.
+//
+// The identifier is used as the routing key for both /-prefixed commands and
+// callback payloads — the difference is registration: pass the result to
+// Plugin.AddCommand/Plugin.Command for message routing, or to
+// Plugin.AddPayload/Plugin.Payload for callback_data routing.
+//
+// For /-commands the identifier must not include the leading slash
+// (e.g. "start", not "/start") and should match [_a-z0-9]{1,32} to satisfy
+// Telegram's BotCommand validation. Payload identifiers may use any bytes
+// that fit Telegram's callback_data limit, though the configured payload
+// encoding may impose its own restrictions.
+func NewCommand[T any](command string, exec CommandExecutor[T], args ...CommandArg) *Command[T] {
+	return &Command[T]{command, "", exec, 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
+}
+
+func (c *Command[T]) validateArgs(args []string) error {
+	for i := range c.args.Len() {
+		if i >= len(args) && c.args.Get(i).required {
+			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 // Skip validation for CommandValueAny.
+		}
+		if !cmdArg.regex.MatchString(arg) {
+			return ErrCmdArgRegexpMismatch
+		}
+	}
+	return nil
+}
+
+func (c *Command[T]) clone() *Command[T] {
+	if c == nil {
+		return nil
+	}
+
+	cloned := *c
+	cloned.args = append(extypes.Slice[CommandArg](nil), c.args...)
+	cloned.middlewares = append(extypes.Slice[Middleware[T]](nil), c.middlewares...)
+	return &cloned
+}
+
+// CommandGroup builds a set of commands with a shared name prefix and middleware.
+type CommandGroup[T any] struct {
+	prefix      string
+	middlewares extypes.Slice[Middleware[T]]
+	commands    extypes.Slice[*Command[T]]
+}
+
+// NewCommandGroup creates a command group that prefixes every added command.
+func NewCommandGroup[T any](prefix string) *CommandGroup[T] {
+	return &CommandGroup[T]{
+		prefix: prefix,
+
+		middlewares: make([]Middleware[T], 0),
+		commands:    make([]*Command[T], 0),
+	}
+}
+
+// Use adds middleware that runs before each command's own middleware.
+func (g *CommandGroup[T]) Use(m Middleware[T]) *CommandGroup[T] {
+	g.middlewares = append(g.middlewares, m)
+	return g
+}
+
+// AddCommand adds a prefixed copy of cmd to the group.
+func (g *CommandGroup[T]) AddCommand(cmd *Command[T]) *CommandGroup[T] {
+	if cmd == nil {
+		return g
+	}
+	newCmd := cmd.clone()
+	newCmd.command = g.prefix + cmd.command
+	g.commands = g.commands.Push(newCmd)
+	return g
+}
+
+// Build returns command copies with group middleware prepended.
+func (g *CommandGroup[T]) Build() []*Command[T] {
+	commands := make([]*Command[T], 0)
+	for _, cmd := range g.commands {
+		cloned := cmd.clone()
+		cloned.middlewares = append(
+			append(extypes.Slice[Middleware[T]]{}, g.middlewares...),
+			cloned.middlewares...,
+		)
+		commands = append(commands, cloned)
+	}
+	return commands
+}

doc.go

@@ -5,7 +5,7 @@ Core concepts:
 
   - Bot manages Telegram API access, update processing, logging, rate limiting, and dependency injection.
   - Plugins group commands, payloads, and non-command update handlers behind shared middleware.
-  - MsgContext provides access to the current update and reply/edit/delete helpers.
+  - MessageContext provides access to the current update and reply/edit/delete helpers.
   - InlineKeyboard builds callback-driven keyboards and structured payloads.
   - DraftProvider accumulates multi-step replies before sending them.
   - L10n stores key-based translations with fallback behavior.
@@ -13,21 +13,21 @@ Core concepts:
 
 Example usage:
 
-	bot, err := laniakea.NewBot[*mydb.DBContext](laniakea.LoadOptsFromEnv())
+	bot, err := laniakea.NewBot[*mydb.AppData](laniakea.LoadOptsFromEnv())
 	if err != nil {
 	    return err
 	}
-	bot.DatabaseContext(myDB).
+	bot.SetAppData(myDB).
 	    AddUpdateType(tgapi.UpdateTypeMessage).
 	    AddPrefixes("/", "!").
 	    AddPlugins(&startPlugin, &helpPlugin).
 	    AddMiddleware(authMiddleware, logMiddleware).
 	    AddRunner(cleanupRunner).
-	    AddL10n(l10n.New())
+	    SetL10n(l10n.New())
 
 	return bot.Run()
 
-Configure bots, plugins, and localization before starting Run or RunWithContext.
+Configure bots, plugins, and localization before starting Run, RunWithContext, or RunWebhookWithContext.
 Runtime accessors are safe for concurrent use unless stated otherwise.
 */
 package laniakea

drafts.go

@@ -1,41 +1,38 @@
 package laniakea
 
 import (
-	"errors"
 	"math/rand/v2"
 	"sync"
 	"sync/atomic"
 
-	"git.nix13.pw/scuroneko/laniakea/tgapi"
+	"git.scuroneko.dev/scuroneko/laniakea/tgapi"
 )
 
-// ErrDraftChatIDZero is returned when a draft is used without setting a chat ID.
+type draftIDGenerator interface {
-var ErrDraftChatIDZero = errors.New("zero draft chat ID")
-
-// Interface for generating unique draft IDs.
-type draftIdGenerator interface {
-	// Next returns the next unique draft ID.
 	Next() uint64
 }
 
-// RandomDraftIdGenerator generates draft IDs using cryptographically secure random numbers.
+// RandomDraftIDGenerator generates draft IDs using math/rand/v2.
-// Suitable for distributed systems or when ID predictability is undesirable.
+//
-type RandomDraftIdGenerator struct{}
+// Suitable for general use thanks to the wide 64-bit value space. Not suitable
+// for security-sensitive purposes — use crypto/rand if unpredictability against
+// an adversary matters.
+type RandomDraftIDGenerator struct{}
 
 // Next returns a random 64-bit unsigned integer.
-func (g *RandomDraftIdGenerator) Next() uint64 {
+func (g *RandomDraftIDGenerator) Next() uint64 {
 	return rand.Uint64()
 }
 
-// LinearDraftIdGenerator generates draft IDs using a monotonically increasing counter.
+// LinearDraftIDGenerator generates draft IDs using a monotonically increasing counter.
 // Useful for debugging, persistence, or when drafts must be ordered.
-type LinearDraftIdGenerator struct {
+type LinearDraftIDGenerator struct {
-	lastId atomic.Uint64
+	lastID atomic.Uint64
 }
 
 // Next returns the next linear ID, atomically incremented.
-func (g *LinearDraftIdGenerator) Next() uint64 {
+func (g *LinearDraftIDGenerator) Next() uint64 {
-	return g.lastId.Add(1)
+	return g.lastID.Add(1)
 }
 
 // DraftProvider manages a collection of Drafts and a shared draft ID generator.
@@ -45,16 +42,16 @@ type DraftProvider struct {
 	mu        sync.RWMutex
 	api       *tgapi.API
 	drafts    map[uint64]*Draft
-	generator draftIdGenerator
+	generator draftIDGenerator
 }
 
 // NewRandomDraftProvider creates a new DraftProvider using random draft IDs.
 //
-// The provider will use cryptographically secure random numbers for draft IDs.
+// The provider will use 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{},
+		api: api, generator: &RandomDraftIDGenerator{},
 		drafts: make(map[uint64]*Draft),
 	}
 }
@@ -67,8 +64,8 @@ func NewRandomDraftProvider(api *tgapi.API) *DraftProvider {
 // 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 := &LinearDraftIDGenerator{}
-	g.lastId.Store(startValue)
+	g.lastID.Store(startValue)
 	return &DraftProvider{
 		api:       api,
 		generator: g,
@@ -190,8 +187,7 @@ func (d *Draft) Clear() {
 
 // 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
+// You may call it manually if you want to cancel a draft without sending it.
-// want to cancel a draft without sending it.
 func (d *Draft) Delete() {
 	if d.provider != nil {
 		d.provider.mu.Lock()
@@ -221,8 +217,11 @@ func (d *Draft) Flush() error {
 	if d.chatID == 0 {
 		return ErrDraftChatIDZero
 	}
+	if err := validateMessageText(d.Message); err != nil {
+		return err
+	}
 
-	params := tgapi.SendMessageP{
+	params := tgapi.SendMessage{
 		ChatID:    d.chatID,
 		ParseMode: d.parseMode,
 		Entities:  d.entities,
@@ -239,13 +238,21 @@ func (d *Draft) Flush() error {
 	return err
 }
 
-// Internal helper for Push that updates the server-side draft.
+// The candidate Message (current content + new text) is validated before any
+// mutation, so a validation failure leaves the draft unchanged. After the
+// validation passes, Message is committed locally regardless of whether the
+// API call succeeds (per the Push docs: local state reflects the user's
+// intent, network failures can be retried).
 func (d *Draft) push(text string) error {
 	if d.chatID == 0 {
 		return ErrDraftChatIDZero
 	}
-	d.Message += text
+	candidate := d.Message + text
-	params := tgapi.SendMessageDraftP{
+	if err := validateMessageText(candidate); err != nil {
+		return err
+	}
+	d.Message = candidate
+	params := tgapi.SendMessageDraft{
 		ChatID:    d.chatID,
 		DraftID:   d.ID,
 		Text:      d.Message,

drafts_test.go

@@ -1,36 +1,73 @@
 package laniakea
 
 import (
+	"errors"
+	"strings"
 	"testing"
 
-	"git.nix13.pw/scuroneko/laniakea/tgapi"
+	"git.scuroneko.dev/scuroneko/laniakea/tgapi"
-	"git.nix13.pw/scuroneko/slog"
+	"git.scuroneko.dev/scuroneko/sneklog/v2"
 )
 
 func TestDraftFlushRequiresChatID(t *testing.T) {
 	draft := NewRandomDraftProvider(&tgapi.API{}).NewDraft(tgapi.ParseNone)
 	draft.Message = "hello"
 
-	if err := draft.Flush(); err != ErrDraftChatIDZero {
+	if err := draft.Flush(); !errors.Is(err, ErrDraftChatIDZero) {
 		t.Fatalf("expected ErrDraftChatIDZero, got %v", err)
 	}
 }
 
 func TestMsgContextNewDraftWorksWithoutLimiter(t *testing.T) {
-	ctx := &MsgContext{
+	ctx := &MessageContext{
-		Api: &tgapi.API{},
+		API: &tgapi.API{},
 		Msg: &tgapi.Message{
-			Chat: &tgapi.Chat{ID: 42, Type: string(tgapi.ChatTypePrivate)},
+			Chat: &tgapi.Chat{ID: 42, Type: tgapi.ChatTypePrivate},
 		},
-		Logger:        slog.CreateLogger(),
+		Logger:        sneklog.NewLogger(),
 		draftProvider: NewRandomDraftProvider(&tgapi.API{}),
 	}
 
 	draft := ctx.NewDraft()
 	if draft == nil {
 		t.Fatal("expected draft")
+		return
 	}
 	if draft.chatID != 42 {
 		t.Fatalf("unexpected chat id: %d", draft.chatID)
 	}
 }
+
+func TestDraftFlushRejectsLongMessage(t *testing.T) {
+	draft := NewRandomDraftProvider(&tgapi.API{}).NewDraft(tgapi.ParseNone).SetChat(42, 0)
+	draft.Message = strings.Repeat("a", maxMessageTextLen+1)
+
+	if err := draft.Flush(); !errors.Is(err, ErrMessageTooLong) {
+		t.Fatalf("expected ErrMessageTooLong, got %v", err)
+	}
+}
+
+func TestDraftPushRejectsLongMessage(t *testing.T) {
+	draft := NewRandomDraftProvider(&tgapi.API{}).NewDraft(tgapi.ParseNone).SetChat(42, 0)
+
+	if err := draft.Push(strings.Repeat("a", maxMessageTextLen+1)); !errors.Is(err, ErrMessageTooLong) {
+		t.Fatalf("expected ErrMessageTooLong, got %v", err)
+	}
+}
+
+// TestDraftPushLeavesMessageUnchangedOnValidationFailure covers the validation
+// order fix: when the candidate Message (current + new text) overflows the
+// Telegram limit, the existing Message must remain intact so callers can
+// recover and retry with a shorter payload instead of finding the draft in
+// a half-mutated state.
+func TestDraftPushLeavesMessageUnchangedOnValidationFailure(t *testing.T) {
+	draft := NewRandomDraftProvider(&tgapi.API{}).NewDraft(tgapi.ParseNone).SetChat(42, 0)
+	draft.Message = "hello"
+
+	if err := draft.Push(strings.Repeat("a", maxMessageTextLen+1)); !errors.Is(err, ErrMessageTooLong) {
+		t.Fatalf("expected ErrMessageTooLong, got %v", err)
+	}
+	if draft.Message != "hello" {
+		t.Fatalf("expected draft Message to stay %q, got %q", "hello", draft.Message)
+	}
+}

error_model.go

@@ -0,0 +1,59 @@
+package laniakea
+
+import "errors"
+
+type classifiedError struct {
+	err          error
+	userVisible  bool
+	internalOnly bool
+}
+
+func (e *classifiedError) Error() string {
+	if e == nil || e.err == nil {
+		return ""
+	}
+	return e.err.Error()
+}
+
+func (e *classifiedError) Unwrap() error {
+	if e == nil {
+		return nil
+	}
+	return e.err
+}
+
+// AsUserError marks err as safe to show to the user through the centralized
+// handler error flow.
+func AsUserError(err error) error {
+	if err == nil {
+		return nil
+	}
+	return &classifiedError{err: err, userVisible: true}
+}
+
+// AsInternalError marks err as internal-only so it will be logged but not sent
+// to the user through the centralized handler error flow.
+func AsInternalError(err error) error {
+	if err == nil {
+		return nil
+	}
+	return &classifiedError{err: err, internalOnly: true}
+}
+
+// IsUserError reports whether err was explicitly marked as user-visible.
+func IsUserError(err error) bool {
+	var classified *classifiedError
+	if !errors.As(err, &classified) {
+		return false
+	}
+	return classified.userVisible
+}
+
+// IsInternalError reports whether err was explicitly marked as internal-only.
+func IsInternalError(err error) bool {
+	var classified *classifiedError
+	if !errors.As(err, &classified) {
+		return false
+	}
+	return classified.internalOnly
+}

errors.go

@@ -0,0 +1,112 @@
+package laniakea
+
+import (
+	"errors"
+	"fmt"
+	"unicode/utf8"
+)
+
+const (
+	maxMessageTextLen    = 4096
+	maxMessageCaptionLen = 1024
+)
+
+var (
+	// ErrEmptyMessage reports that a required message text is empty.
+	ErrEmptyMessage = errors.New("empty message")
+	// ErrMessageTooLong reports that a message exceeds Telegram's text limit.
+	ErrMessageTooLong = errors.New("message too long")
+	// ErrCaptionTooLong reports that a caption exceeds Telegram's caption limit.
+	ErrCaptionTooLong = errors.New("caption too long")
+	// ErrMessageSplitImpossible reports that automatic message splitting cannot preserve semantics.
+	ErrMessageSplitImpossible = errors.New("message split is impossible")
+	// ErrPayloadTypeMismatch reports that callback payload encoding does not match bot policy.
+	ErrPayloadTypeMismatch = errors.New("payload type mismatch")
+	// ErrDraftChatIDZero reports that a draft has no target chat ID.
+	ErrDraftChatIDZero = errors.New("zero draft chat ID")
+	// ErrMessageNil reports that a required message value is nil.
+	ErrMessageNil = errors.New("message is nil")
+	// ErrMessageContextNil reports that an operation requires ctx.Msg but none is set.
+	ErrMessageContextNil = errors.New("message context is nil")
+	// ErrEditTargetMissing reports that an edit operation has no message target.
+	ErrEditTargetMissing = errors.New("edit target is missing")
+	// ErrCallbackMessageMissing reports that a callback operation has no callback message target.
+	ErrCallbackMessageMissing = errors.New("callback message is missing")
+	// ErrDraftProviderNil reports that draft creation was requested without a draft provider.
+	ErrDraftProviderNil = errors.New("draft provider is nil")
+	// ErrAPIIsNil reports that an operation requires an API client but none is set.
+	ErrAPIIsNil = errors.New("api is nil")
+	// ErrMessageIDZero reports that an operation requires a non-zero message ID.
+	ErrMessageIDZero = errors.New("message ID is zero")
+)
+var (
+	// ErrBindArgsTargetNotPointer reports that BindArgs received a nil or non-pointer destination.
+	ErrBindArgsTargetNotPointer = errors.New("bind args: dst must be a non-nil pointer")
+	// ErrBindArgsTargetNotStruct reports that BindArgs received a pointer to a non-struct value.
+	ErrBindArgsTargetNotStruct = errors.New("bind args: dst must point to a struct")
+	// ErrBindArgsUnsupportedFieldType reports that BindArgs encountered an unsupported field kind.
+	ErrBindArgsUnsupportedFieldType = errors.New("bind args: unsupported field type")
+	// ErrBindArgsConversion reports that BindArgs could not convert a string argument into a field type.
+	ErrBindArgsConversion = errors.New("bind args: conversion failed")
+	// ErrCantFindSession reports that no scene session matches the current context.
+	ErrCantFindSession = errors.New("can't find session for this context")
+	// ErrSceneNotFound reports that the requested scene is not registered.
+	ErrSceneNotFound = errors.New("scene not found")
+	// ErrSceneStepNotFound reports that the requested scene step is not registered.
+	ErrSceneStepNotFound = errors.New("scene step not found")
+	// ErrNotInScene reports that the current context has no active scene session.
+	ErrNotInScene = errors.New("not in scene")
+	// ErrSceneEntryNotSet reports that a scene has no configured entry step.
+	ErrSceneEntryNotSet = errors.New("scene entry step not set")
+	// ErrSceneRuntimeNil reports that scene APIs were used without an attached runtime.
+	ErrSceneRuntimeNil = errors.New("scene runtime is nil")
+)
+
+var (
+	// ErrNilBotWebhookOpts reports that a nil BotWebhookOpts was passed.
+	ErrNilBotWebhookOpts = errors.New("nil BotWebhookOpts")
+	// ErrNoBotWebhookOptsURL reports that BotWebhookOpts.URL is empty.
+	ErrNoBotWebhookOptsURL = errors.New("empty BotWebhookOpts.URL")
+	// ErrBotWebhookOptsMaxConnectionsRange reports that BotWebhookOpts.MaxConnections is out of range.
+	ErrBotWebhookOptsMaxConnectionsRange = errors.New("BotWebhookOpts.MaxConnections must be between 1 and 100")
+	// ErrBotUploaderWhenCertificate reports that a certificate was set without an uploader.
+	ErrBotUploaderWhenCertificate = errors.New("bot uploader nil, but certificate set")
+	// ErrStatusPathSecretRequired reports that UseStatusPath requires SecretToken to be set.
+	ErrStatusPathSecretRequired = errors.New("SecretToken required when UseStatusPath is enabled")
+	// ErrSetWebhookFailed reports that Telegram rejected the setWebhook request.
+	ErrSetWebhookFailed = errors.New("failed to set webhook")
+	// ErrBotAPINil reports that an operation requires an API client but none is set.
+	ErrBotAPINil = errors.New("bot api is nil")
+	// ErrBotWebhookOptsEmptyPath reports that BotWebhookOpts.Path is empty.
+	ErrBotWebhookOptsEmptyPath = errors.New("empty BotWebhookOpts.Path")
+	// ErrBotWebhookOptsPathNoSlash reports that BotWebhookOpts.Path does not start with '/'.
+	ErrBotWebhookOptsPathNoSlash = errors.New("BotWebhookOpts.Path must start with '/'")
+	// ErrBotWebhookOptsPathHasQueryOrFragment reports that BotWebhookOpts.Path contains a query or fragment.
+	ErrBotWebhookOptsPathHasQueryOrFragment = errors.New("BotWebhookOpts.Path must not contain query or fragment")
+	// ErrBotWebhookOptsPathCollidesStatus reports that BotWebhookOpts.Path collides with the reserved /status endpoint.
+	ErrBotWebhookOptsPathCollidesStatus = errors.New("BotWebhookOpts.Path must not be '/status' when status path is enabled")
+	// ErrBotWebhookTLSFilesIncomplete reports that only one of the two TLS files was provided.
+	ErrBotWebhookTLSFilesIncomplete = errors.New("you must specify both private and public keys")
+	// ErrBotWebhookTLSFilesTooMany reports that more than two TLS files were provided.
+	ErrBotWebhookTLSFilesTooMany = errors.New("too many files; you must specify only private and public keys")
+)
+
+func validateMessageText(text string) error {
+	length := utf8.RuneCountInString(text)
+	switch {
+	case length == 0:
+		return ErrEmptyMessage
+	case length > maxMessageTextLen:
+		return fmt.Errorf("%w: got %d, limit %d", ErrMessageTooLong, length, maxMessageTextLen)
+	default:
+		return nil
+	}
+}
+
+func validateCaptionText(text string) error {
+	length := utf8.RuneCountInString(text)
+	if length > maxMessageCaptionLen {
+		return fmt.Errorf("%w: got %d, limit %d", ErrCaptionTooLong, length, maxMessageCaptionLen)
+	}
+	return nil
+}

go.mod

@@ -1,19 +1,12 @@
-module git.nix13.pw/scuroneko/laniakea
+module git.scuroneko.dev/scuroneko/laniakea
 
 go 1.26
 
 retract v1.0.0-rc.5
 
 require (
-	git.nix13.pw/scuroneko/extypes v1.2.2
+	git.scuroneko.dev/scuroneko/extypes v1.2.3
-	git.nix13.pw/scuroneko/slog v1.1.2
+	git.scuroneko.dev/scuroneko/sneklog/v2 v2.3.0
-	github.com/alitto/pond/v2 v2.7.0
+	github.com/alitto/pond/v2 v2.7.1
 	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.42.0 // indirect
-)

go.sum

@@ -1,17 +1,8 @@
-git.nix13.pw/scuroneko/extypes v1.2.2 h1:N54c1ejrPs1yfIkvYuwqI7B1+8S9mDv2GqQA6sct4dk=
+git.scuroneko.dev/scuroneko/extypes v1.2.3 h1:n7QsfTZEn9fJNZLXGH/LkNq4cADaRk+LTu6LNMv9y6s=
-git.nix13.pw/scuroneko/extypes v1.2.2/go.mod h1:b4XYk1OW1dVSiE2MT/OMuX/K/UItf1swytX6eroVYnk=
+git.scuroneko.dev/scuroneko/extypes v1.2.3/go.mod h1:MhYpXC6sloLOpoM2guf64eSOrz+ET/QJZ8toobc3Ors=
-git.nix13.pw/scuroneko/slog v1.1.2 h1:pl7tV5FN25Yso7sLYoOgBXi9+jLo5BDJHWmHlNPjpY0=
+git.scuroneko.dev/scuroneko/sneklog/v2 v2.3.0 h1:gaPe5azwuDTh48jRB/P2FUgOs7f1ToNr0S+NBizKvY8=
-git.nix13.pw/scuroneko/slog v1.1.2/go.mod h1:UcfRIHDqpVQHahBGM93awLDK8//AsAvOqBwwbWqMkjM=
+git.scuroneko.dev/scuroneko/sneklog/v2 v2.3.0/go.mod h1:q8XnLXzLdGjW0Jtcbh9/+G9WmfD68rsPQvLXEPxvum4=
-github.com/alitto/pond/v2 v2.7.0 h1:c76L+yN916m/DRXjGCeUBHHu92uWnh/g1bwVk4zyyXg=
+github.com/alitto/pond/v2 v2.7.1 h1:QxMbcfjcVTa0pyxX5Ib1226mM8u8D7gKUVkCUU4DYIw=
-github.com/alitto/pond/v2 v2.7.0/go.mod h1:xkjYEgQ05RSpWdfSd1nM3OVv7TBhLdy7rMp3+2Nq+yE=
+github.com/alitto/pond/v2 v2.7.1/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.42.0 h1:omrd2nAlyT5ESRdCLYdm3+fMfNFE/+Rf4bDIQImRJeo=
-golang.org/x/sys v0.42.0/go.mod h1:4GL1E5IUh+htKOUEOaiffhrAeqysfVGipDYzABqnCmw=
 golang.org/x/time v0.15.0 h1:bbrp8t3bGUeFOx08pvsMYRTCVSMk89u4tKbNOZbp88U=
 golang.org/x/time v0.15.0/go.mod h1:Y4YMaQmXwGQZoFaVFk4YpCt4FLQMYKZe9oeV/f4MSno=

handler.go

@@ -1,166 +1,138 @@
 package laniakea
 
 import (
+	"context"
 	"encoding/base64"
 	"encoding/json"
 	"errors"
 	"fmt"
 	"strings"
+	"time"
 
-	"git.nix13.pw/scuroneko/laniakea/tgapi"
+	"git.scuroneko.dev/scuroneko/laniakea/tgapi"
 )
 
 // ErrInvalidPayloadType is returned when callback payload encoding type is unknown.
 var ErrInvalidPayloadType = errors.New("invalid payload type")
 
-func (bot *Bot[T]) handle(u *tgapi.Update) {
+// ErrInvalidPayload reports that a callback payload could not be decoded under the
+// expected encoding (e.g. the compact format separator is missing).
+var ErrInvalidPayload = errors.New("invalid payload")
+
+func (bot *Bot[T]) handle(parentCtx context.Context, u *tgapi.Update) {
 	defer func() {
 		if r := recover(); r != nil {
-			bot.logger.Errorln(fmt.Sprintf("panic in handle: %v", r))
+			if bot.logger != nil {
+				bot.logger.Errorln(fmt.Sprintf("panic in handle: %v", r))
+			}
+
+			err, ok := r.(error)
+			if !ok {
+				err = fmt.Errorf("%v", r)
+			}
+			bot.safeEmitEvent(parentCtx, ErrorEvent{
+				UpdateID:   u.UpdateID,
+				UpdateType: u.Type,
+				Err:        err,
+				UserFacing: false,
+			})
 		}
 	}()
+	startTime := time.Now()
 
-	ctx := &MsgContext{
+	ctx, cancel := context.WithCancel(parentCtx)
-		Update: *u, Api: bot.api,
+	defer cancel()
+
+	msgCtx := &MessageContext{
+		Update: *u, API: bot.api,
 		Logger:        bot.logger,
 		errorTemplate: bot.errorTemplate,
 		l10n:          bot.l10n,
 		draftProvider: bot.draftProvider,
+		sceneRuntime:  bot,
+		observer:      bot.observer,
 		payloadType:   bot.payloadType,
+		botID:         bot.userID,
+		ctx:           ctx,
 	}
-	bot.prepareUpdateCtx(u, ctx)
+	bot.prepareUpdateCtx(u, msgCtx)
+	bot.safeEmitEvent(ctx, UpdateReceivedEvent{
+		UpdateID:   u.UpdateID,
+		UpdateType: u.Type,
+		FromID:     msgCtx.FromID,
+		ChatID:     msgCtx.ChatID,
+	})
 
 	for _, middleware := range bot.middlewares {
-		if !middleware.Execute(ctx, bot.dbContext) {
+		if !middleware.Execute(msgCtx, bot.appData) {
+			bot.safeEmitEvent(ctx, UpdateHandledEvent{
+				UpdateID:   u.UpdateID,
+				UpdateType: u.Type,
+				FromID:     msgCtx.FromID,
+				ChatID:     msgCtx.ChatID,
+				Duration:   time.Since(startTime),
+				Handled:    false,
+			})
 			return
 		}
 	}
 
-	switch u.Type {
+	sceneHandled, err := bot.tryHandleScene(msgCtx)
-	case tgapi.UpdateTypeMessage, tgapi.UpdateTypeChannelPost:
-		bot.handleMessage(u, ctx)
-	case tgapi.UpdateTypeCallbackQuery:
-		bot.handleCallback(u, ctx)
-	default:
-		bot.handleUpdate(u, ctx)
-	}
-}
-
-func (bot *Bot[T]) handleMessage(update *tgapi.Update, ctx *MsgContext) {
-	var msg *tgapi.Message
-	if update.Message != nil {
-		msg = update.Message
-	} else if update.ChannelPost != nil {
-		msg = update.ChannelPost
-	} else {
-		return
-	}
-
-	var text string
-	if len(msg.Text) > 0 {
-		text = msg.Text
-	} else if len(msg.Caption) > 0 {
-		text = msg.Caption
-	} else {
-		return
-	}
-
-	text = strings.TrimSpace(text)
-	prefix, hasPrefix := bot.checkPrefixes(text)
-	if !hasPrefix {
-		return
-	}
-
-	ctx.Prefix = prefix
-	ctx.Update = *update
-
-	// Убираем префикс
-	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 {
-		if _, exists := plugin.commands[cmd]; exists {
-			ctx.Text = args
-			ctx.Args = strings.Fields(args) // Убирает лишние пробелы
-
-			if plugin.logger != nil {
-				ctx.Logger = plugin.logger
-			}
-			if !plugin.executeMiddlewares(ctx, bot.dbContext) {
-				return
-			}
-			plugin.executeCmd(cmd, ctx, bot.dbContext)
-			return
-		}
-	}
-}
-
-func (bot *Bot[T]) handleCallback(update *tgapi.Update, ctx *MsgContext) {
-	data, err := bot.decodePayload(update.CallbackQuery.Data)
 	if err != nil {
 		bot.logger.Errorln(err)
+		bot.safeEmitEvent(ctx, UpdateHandledEvent{
+			UpdateID:   u.UpdateID,
+			UpdateType: u.Type,
+			FromID:     msgCtx.FromID,
+			ChatID:     msgCtx.ChatID,
+			Duration:   time.Since(startTime),
+			Handled:    false,
+		})
+		bot.safeEmitEvent(ctx, ErrorEvent{
+			UpdateID:    u.UpdateID,
+			UpdateType:  u.Type,
+			Plugin:      "bot",
+			HandlerKind: HandlerSceneKind,
+			HandlerName: "tryHandleScene",
+			FromID:      msgCtx.FromID,
+			ChatID:      msgCtx.ChatID,
+			Err:         err,
+			UserFacing:  false,
+		})
+		return
+	}
+	if sceneHandled {
+		bot.safeEmitEvent(ctx, UpdateHandledEvent{
+			UpdateID:   u.UpdateID,
+			UpdateType: u.Type,
+			FromID:     msgCtx.FromID,
+			ChatID:     msgCtx.ChatID,
+			Duration:   time.Since(startTime),
+			Handled:    true,
+		})
 		return
 	}
 
-	ctx.Args = data.Args
+	handled := false
-
+	switch u.Type {
-	for _, plugin := range bot.plugins {
+	case tgapi.UpdateTypeMessage, tgapi.UpdateTypeChannelPost:
-		_, ok := plugin.payloads[data.Command]
+		handled = bot.handleMessage(u, msgCtx)
-		if !ok {
+	case tgapi.UpdateTypeCallbackQuery:
-			continue
+		handled = bot.handleCallback(u, msgCtx)
-		}
+	default:
-
+		handled = bot.handleUpdate(u, msgCtx)
-		ctx.Logger = plugin.logger
-		if ctx.Logger == nil {
-			ctx.Logger = bot.logger
-		}
-		if !plugin.executeMiddlewares(ctx, bot.dbContext) {
-			return
-		}
-		plugin.executePayload(data.Command, ctx, bot.dbContext)
-		return
 	}
+	bot.safeEmitEvent(ctx, UpdateHandledEvent{
+		UpdateID:   u.UpdateID,
+		UpdateType: u.Type,
+		FromID:     msgCtx.FromID,
+		ChatID:     msgCtx.ChatID,
+		Duration:   time.Since(startTime),
+		Handled:    handled,
+	})
 }
 
-func (bot *Bot[T]) handleUpdate(u *tgapi.Update, ctx *MsgContext) {
+func cloneMsgContext(src *MessageContext) *MessageContext {
-	for _, plugin := range bot.plugins {
-		handler, ok := plugin.handlers[u.Type]
-		if !ok {
-			continue
-		}
-
-		pluginCtx := cloneMsgContext(ctx)
-		if plugin.logger != nil {
-			pluginCtx.Logger = plugin.logger
-		}
-		if !plugin.executeMiddlewares(pluginCtx, bot.dbContext) {
-			continue
-		}
-		handler(pluginCtx, bot.dbContext)
-	}
-}
-
-func cloneMsgContext(src *MsgContext) *MsgContext {
 	cloned := *src
 	if src.Args != nil {
 		cloned.Args = append([]string(nil), src.Args...)
@@ -168,134 +140,22 @@ func cloneMsgContext(src *MsgContext) *MsgContext {
 	return &cloned
 }
 
-func (bot *Bot[T]) prepareUpdateCtx(u *tgapi.Update, ctx *MsgContext) {
+func encodeJSONPayload(d CallbackData) (string, error) {
-	var from *tgapi.User
-	switch u.Type {
-	case tgapi.UpdateTypeMessage:
-		if u.Message != nil {
-			ctx.Msg = u.Message
-		}
-	case tgapi.UpdateTypeEditedMessage:
-		if u.EditedMessage != nil {
-			ctx.Msg = u.EditedMessage
-		}
-	case tgapi.UpdateTypeChannelPost:
-		if u.ChannelPost != nil {
-			ctx.Msg = u.ChannelPost
-		}
-	case tgapi.UpdateTypeEditedChannelPost:
-		if u.EditedChannelPost != nil {
-			ctx.Msg = u.EditedChannelPost
-		}
-	case tgapi.UpdateTypeBusinessMessage:
-		if u.BusinessMessage != nil {
-			ctx.Msg = u.BusinessMessage
-		}
-	case tgapi.UpdateTypeEditedBusinessMessage:
-		if u.EditedBusinessMessage != nil {
-			ctx.Msg = u.EditedBusinessMessage
-		}
-	case tgapi.UpdateTypeInlineQuery:
-		if u.InlineQuery != nil {
-			from = &u.InlineQuery.From
-		}
-	case tgapi.UpdateTypeChosenInlineResult:
-		if u.ChosenInlineResult != nil {
-			from = &u.ChosenInlineResult.From
-		}
-	case tgapi.UpdateTypeCallbackQuery:
-		if u.CallbackQuery != nil {
-			if u.CallbackQuery.Message != nil {
-				ctx.Msg = u.CallbackQuery.Message
-				ctx.CallbackMsgId = u.CallbackQuery.Message.MessageID
-			}
-			if u.CallbackQuery.InlineMessageID != nil {
-				ctx.InlineMsgId = *u.CallbackQuery.InlineMessageID
-			}
-			ctx.CallbackQueryId = u.CallbackQuery.ID
-			from = &u.CallbackQuery.From
-		}
-	case tgapi.UpdateTypeShippingQuery:
-		if u.ShippingQuery != nil {
-			from = &u.ShippingQuery.From
-		}
-	case tgapi.UpdateTypePreCheckoutQuery:
-		if u.PreCheckoutQuery != nil {
-			from = &u.PreCheckoutQuery.From
-		}
-	case tgapi.UpdateTypePurchasedPaidMedia:
-		if u.PurchasedPaidMedia != nil {
-			from = &u.PurchasedPaidMedia.From
-		}
-	case tgapi.UpdateTypeMyChatMember:
-		if u.MyChatMember != nil {
-			from = &u.MyChatMember.From
-		}
-	case tgapi.UpdateTypeChatMember:
-		if u.ChatMember != nil {
-			from = &u.ChatMember.From
-		}
-	case tgapi.UpdateTypeChatJoinRequest:
-		if u.ChatJoinRequest != nil {
-			from = &u.ChatJoinRequest.From
-		}
-	case tgapi.UpdateTypeBusinessConnection:
-		if u.BusinessConnection != nil {
-			from = &u.BusinessConnection.User
-		}
-	case tgapi.UpdateTypePollAnswer:
-		if u.PollAnswer != nil {
-			from = &u.PollAnswer.User
-		}
-	case tgapi.UpdateTypeMessageReaction:
-		if u.MessageReaction != nil {
-			from = u.MessageReaction.User
-		}
-	case tgapi.UpdateTypeChatBoost:
-		if u.ChatBoost != nil {
-			from = &u.ChatBoost.Boost.Source.User
-		}
-	case tgapi.UpdateTypeRemovedChatBoost:
-		if u.RemovedChatBoost != nil {
-			from = &u.RemovedChatBoost.Source.User
-		}
-	}
-	if ctx.Msg != nil && from == nil {
-		from = ctx.Msg.From
-	}
-	if from != nil {
-		ctx.From = from
-		ctx.FromID = from.ID
-	}
-	ctx.Update = *u
-}
-
-func (bot *Bot[T]) checkPrefixes(text string) (string, bool) {
-	for _, prefix := range bot.prefixes {
-		if prefix == "" {
-			continue
-		}
-		if strings.HasPrefix(text, prefix) {
-			return prefix, true
-		}
-	}
-	return "", false
-}
-
-func encodeJsonPayload(d CallbackData) (string, error) {
 	b, err := json.Marshal(d)
 	if err != nil {
 		return "", err
 	}
 	return string(b), nil
 }
-func decodeJsonPayload(s string) (CallbackData, error) {
+
+func decodeJSONPayload(s string) (CallbackData, error) {
 	var data CallbackData
 	err := json.Unmarshal([]byte(s), &data)
 	return data, err
 }
+
 func encodeBase64Payload(d CallbackData) (string, error) {
-	data, err := encodeJsonPayload(d)
+	data, err := encodeJSONPayload(d)
 	if err != nil {
 		return "", err
 	}
@@ -304,35 +164,166 @@ func encodeBase64Payload(d CallbackData) (string, error) {
 	return string(dst), nil
 }
 
-//	func encodePayload(payloadType BotPayloadType, d CallbackData) (string, error) {
-//		switch payloadType {
-//		case BotPayloadBase64:
-//			return encodeBase64Payload(d)
-//		case BotPayloadJson:
-//			return encodeJsonPayload(d)
-//		}
-//		return "", ErrInvalidPayloadType
-//	}
 func decodeBase64Payload(s string) (CallbackData, error) {
 	b, err := base64.RawURLEncoding.DecodeString(s)
 	if err != nil {
 		return CallbackData{}, err
 	}
-	return decodeJsonPayload(string(b))
+	return decodeJSONPayload(string(b))
 }
-func decodePayload(payloadType BotPayloadType, s string) (CallbackData, error) {
+
+// Compact payload format: cmd|arg1,arg2,...
+// Bytes \, |, and , inside a part are escaped with a leading backslash so the
+// payload round-trips without ambiguity. Encoding/decoding operate byte-wise
+// because all separators are single-byte ASCII; multi-byte UTF-8 code points
+// pass through unchanged.
+
+func encodeCompactPart(s string) string {
+	if !strings.ContainsAny(s, `\|,`) {
+		return s
+	}
+	var b strings.Builder
+	b.Grow(len(s) + 2)
+	for i := 0; i < len(s); i++ {
+		switch s[i] {
+		case '\\', '|', ',':
+			b.WriteByte('\\')
+		}
+		b.WriteByte(s[i])
+	}
+	return b.String()
+}
+
+func decodeCompactPart(s string) string {
+	if !strings.Contains(s, `\`) {
+		return s
+	}
+	var b strings.Builder
+	b.Grow(len(s))
+	for i := 0; i < len(s); i++ {
+		if s[i] == '\\' && i+1 < len(s) {
+			b.WriteByte(s[i+1])
+			i++
+			continue
+		}
+		b.WriteByte(s[i])
+	}
+	return b.String()
+}
+
+func encodeCompactPayload(d CallbackData) (string, error) {
+	var b strings.Builder
+	b.WriteString(encodeCompactPart(d.Command))
+	b.WriteByte('|')
+	for i, a := range d.Args {
+		if i > 0 {
+			b.WriteByte(',')
+		}
+		b.WriteString(encodeCompactPart(a))
+	}
+	return b.String(), nil
+}
+
+func decodeCompactPayload(s string) (CallbackData, error) {
+	sepIdx := -1
+	for i := 0; i < len(s); i++ {
+		if s[i] == '\\' && i+1 < len(s) {
+			i++
+			continue
+		}
+		if s[i] == '|' {
+			sepIdx = i
+			break
+		}
+	}
+	if sepIdx == -1 {
+		return CallbackData{}, ErrInvalidPayload
+	}
+	cmd := decodeCompactPart(s[:sepIdx])
+	argsRaw := s[sepIdx+1:]
+	if argsRaw == "" {
+		return CallbackData{Command: cmd}, nil
+	}
+
+	var args []string
+	start := 0
+	for i := 0; i < len(argsRaw); i++ {
+		if argsRaw[i] == '\\' && i+1 < len(argsRaw) {
+			i++
+			continue
+		}
+		if argsRaw[i] == ',' {
+			args = append(args, decodeCompactPart(argsRaw[start:i]))
+			start = i + 1
+		}
+	}
+	args = append(args, decodeCompactPart(argsRaw[start:]))
+	return CallbackData{Command: cmd, Args: args}, nil
+}
+func encodeCompactBase64Payload(d CallbackData) (string, error) {
+	payload, _ := encodeCompactPayload(d)
+	return base64.RawURLEncoding.EncodeToString([]byte(payload)), nil
+}
+func decodeCompactBase64Payload(s string) (CallbackData, error) {
+	b, err := base64.RawURLEncoding.DecodeString(s)
+	if err != nil {
+		return CallbackData{}, err
+	}
+	return decodeCompactPayload(string(b))
+}
+
+func decodePayloadAs(payloadType BotPayloadType, s string) (CallbackData, error) {
 	switch payloadType {
 	case BotPayloadBase64:
 		return decodeBase64Payload(s)
-	case BotPayloadJson:
+	case BotPayloadJSON:
-		return decodeJsonPayload(s)
+		return decodeJSONPayload(s)
+	case BotPayloadCompact:
+		return decodeCompactPayload(s)
+	case BotPayloadCompactBase64:
+		return decodeCompactBase64Payload(s)
 	}
 	return CallbackData{}, ErrInvalidPayloadType
 }
 
-//	func (bot *Bot[T]) encodePayload(d CallbackData) (string, error) {
+func decodePayload(payloadType BotPayloadType, s string, strict bool) (CallbackData, BotPayloadType, error) {
-//		return encodePayload(bot.payloadType, d)
+	knownTypes := []BotPayloadType{
-//	}
+		BotPayloadBase64,
+		BotPayloadJSON,
+		BotPayloadCompact,
+		BotPayloadCompactBase64,
+	}
+	if _, err := decodePayloadAs(payloadType, ""); errors.Is(err, ErrInvalidPayloadType) {
+		return CallbackData{}, "", ErrInvalidPayloadType
+	}
+
+	data, err := decodePayloadAs(payloadType, s)
+	if err == nil {
+		return data, payloadType, nil
+	}
+	if strict {
+		return CallbackData{}, "", fmt.Errorf("%w: expected %s", ErrPayloadTypeMismatch, payloadType)
+	}
+
+	for _, candidate := range knownTypes {
+		if candidate == payloadType {
+			continue
+		}
+		data, err = decodePayloadAs(candidate, s)
+		if err == nil {
+			return data, candidate, nil
+		}
+	}
+	return CallbackData{}, "", err
+}
+
 func (bot *Bot[T]) decodePayload(s string) (CallbackData, error) {
-	return decodePayload(bot.payloadType, s)
+	data, decodedType, err := decodePayload(bot.payloadType, s, bot.strictPayloadType)
+	if err != nil {
+		return CallbackData{}, err
+	}
+	if decodedType == BotPayloadBase64 && bot.debug && bot.logger != nil {
+		bot.logger.Debugf("decoded callback payload base64->json: raw=%q json=%s", s, data.ToJSON())
+	}
+	return data, nil
 }

keyboard.go

@@ -3,8 +3,8 @@ package laniakea
 import (
 	"fmt"
 
-	"git.nix13.pw/scuroneko/extypes"
+	"git.scuroneko.dev/scuroneko/extypes"
-	"git.nix13.pw/scuroneko/laniakea/tgapi"
+	"git.scuroneko.dev/scuroneko/laniakea/tgapi"
 )
 
 const (
@@ -16,80 +16,118 @@ const (
 	ButtonStylePrimary tgapi.KeyboardButtonStyle = "primary"
 )
 
-// InlineKbButtonBuilder is a fluent builder for creating a single inline keyboard button.
+// InlineKeyboardButtonBuilder is a fluent builder for creating a single inline keyboard button.
 //
-// Use NewInlineKbButton() to start, then chain methods to configure:
+// Use NewInlineKeyboardButton() to start, then chain methods to configure:
-//   - SetIconCustomEmojiId() — adds a custom emoji icon
+//   - SetIconCustomEmojiID() — adds a custom emoji icon
 //   - SetStyle() — sets visual style (danger/success/primary)
-//   - SetUrl() — makes button open a URL
+//   - SetURL() — makes button open a URL
-//   - SetCallbackDataJson() — attaches structured command + args for bot handling
+//   - SetCallbackDataJSON() — 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 {
+type InlineKeyboardButtonBuilder struct {
-	text              string
+	text    string
-	iconCustomEmojiID string
+	emojiID string
-	style             tgapi.KeyboardButtonStyle
+	style   tgapi.KeyboardButtonStyle
-	url               string
+
-	callbackData      string
+	url  string
+	data string
+
+	payloadType BotPayloadType
 }
 
-// NewInlineKbButton creates a new button builder with the given display text.
+// NewInlineKeyboardButton 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 {
+func NewInlineKeyboardButton(text string) InlineKeyboardButtonBuilder {
-	return InlineKbButtonBuilder{text: text}
+	return InlineKeyboardButtonBuilder{text: text}
 }
 
-// SetIconCustomEmojiId sets a custom emoji ID to display as the button's icon.
+// 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 {
+func (b InlineKeyboardButtonBuilder) SetIconCustomEmojiID(id string) InlineKeyboardButtonBuilder {
-	b.iconCustomEmojiID = id
+	b.emojiID = 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 {
+func (b InlineKeyboardButtonBuilder) SetStyle(style tgapi.KeyboardButtonStyle) InlineKeyboardButtonBuilder {
 	b.style = style
 	return b
 }
 
-// SetUrl sets a URL that will be opened when the button is pressed.
+// 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 {
+func (b InlineKeyboardButtonBuilder) SetURL(url string) InlineKeyboardButtonBuilder {
 	b.url = url
 	return b
 }
 
-// SetCallbackDataJson sets a structured callback payload that will be sent to the bot
+// SetPayloadType sets the encoding used by SetCallbackData.
+func (b InlineKeyboardButtonBuilder) SetPayloadType(t BotPayloadType) InlineKeyboardButtonBuilder {
+	b.payloadType = t
+	return b
+}
+
+// SetCallbackDataJSON 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: SetCallbackDataJson("delete_user", 123, "confirm") → {"cmd":"delete_user","args":["123","confirm"]}.
+// Example: SetCallbackDataJSON("delete_user", 123, "confirm") → {"cmd":"delete_user","args":["123","confirm"]}.
-func (b InlineKbButtonBuilder) SetCallbackDataJson(cmd string, args ...any) InlineKbButtonBuilder {
+func (b InlineKeyboardButtonBuilder) SetCallbackDataJSON(cmd string, args ...any) InlineKeyboardButtonBuilder {
-	b.callbackData = NewCallbackData(cmd, args...).ToJson()
+	b.data = NewCallbackData(cmd, args...).ToJSON()
 	return b
 }
 
 // SetCallbackDataBase64 sets a structured callback payload encoded as Base64.
 // This can be useful when the JSON payload exceeds Telegram's callback data length limit.
 // Args are converted to strings using fmt.Sprint.
-func (b InlineKbButtonBuilder) SetCallbackDataBase64(cmd string, args ...any) InlineKbButtonBuilder {
+func (b InlineKeyboardButtonBuilder) SetCallbackDataBase64(cmd string, args ...any) InlineKeyboardButtonBuilder {
-	b.callbackData = NewCallbackData(cmd, args...).ToBase64()
+	b.data = NewCallbackData(cmd, args...).ToBase64()
 	return b
 }
 
-// Internal helper that converts the builder state into a Telegram button.
+// SetCallbackDataCompact sets a structured callback payload encoded as compact text.
-func (b InlineKbButtonBuilder) build() tgapi.InlineKeyboardButton {
+func (b InlineKeyboardButtonBuilder) SetCallbackDataCompact(cmd string, args ...any) InlineKeyboardButtonBuilder {
+	b.data = NewCallbackData(cmd, args...).ToCompact()
+	return b
+}
+
+// SetCallbackDataCompactBase64 sets a compact callback payload encoded as Base64.
+func (b InlineKeyboardButtonBuilder) SetCallbackDataCompactBase64(cmd string, args ...any) InlineKeyboardButtonBuilder {
+	b.data = NewCallbackData(cmd, args...).ToCompactBase64()
+	return b
+}
+
+// SetCallbackData sets a structured callback payload using the configured payload type.
+// The default payload type is JSON.
+func (b InlineKeyboardButtonBuilder) SetCallbackData(cmd string, args ...any) InlineKeyboardButtonBuilder {
+	switch b.payloadType {
+	case BotPayloadJSON:
+		b.data = NewCallbackData(cmd, args...).ToJSON()
+	case BotPayloadBase64:
+		b.data = NewCallbackData(cmd, args...).ToBase64()
+	case BotPayloadCompact:
+		b.data = NewCallbackData(cmd, args...).ToCompact()
+	case BotPayloadCompactBase64:
+		b.data = NewCallbackData(cmd, args...).ToCompactBase64()
+	default:
+		b.data = NewCallbackData(cmd, args...).ToJSON()
+	}
+	return b
+}
+
+func (b InlineKeyboardButtonBuilder) build() tgapi.InlineKeyboardButton {
 	return tgapi.InlineKeyboardButton{
 		Text:              b.text,
 		URL:               b.url,
 		Style:             b.style,
-		IconCustomEmojiID: b.iconCustomEmojiID,
+		IconCustomEmojiID: b.emojiID,
-		CallbackData:      b.callbackData,
+		CallbackData:      b.data,
 	}
 }
 
@@ -107,12 +145,12 @@ type InlineKeyboard struct {
 	payloadType BotPayloadType // Serialization format for callback data (JSON or Base64)
 }
 
-// NewInlineKeyboardJson creates a new keyboard builder with the specified maximum
+// NewInlineKeyboardJSON creates a new keyboard builder with the specified maximum
 // number of buttons per row.
 //
-// Example: NewInlineKeyboardJson(3) creates a keyboard with at most 3 buttons per line.
+// Example: NewInlineKeyboardJSON(3) creates a keyboard with at most 3 buttons per line.
-func NewInlineKeyboardJson(maxRow int) *InlineKeyboard {
+func NewInlineKeyboardJSON(maxRow int) *InlineKeyboard {
-	return NewInlineKeyboard(BotPayloadJson, maxRow)
+	return NewInlineKeyboard(BotPayloadJSON, maxRow)
 }
 
 // NewInlineKeyboardBase64 creates a new keyboard builder with the specified maximum
@@ -123,10 +161,20 @@ func NewInlineKeyboardBase64(maxRow int) *InlineKeyboard {
 	return NewInlineKeyboard(BotPayloadBase64, maxRow)
 }
 
+// NewInlineKeyboardCompact creates a keyboard builder using compact callback payloads.
+func NewInlineKeyboardCompact(maxRow int) *InlineKeyboard {
+	return NewInlineKeyboard(BotPayloadCompact, maxRow)
+}
+
+// NewInlineKeyboardCompactBase64 creates a keyboard builder using Base64-encoded compact payloads.
+func NewInlineKeyboardCompactBase64(maxRow int) *InlineKeyboard {
+	return NewInlineKeyboard(BotPayloadCompactBase64, maxRow)
+}
+
 // NewInlineKeyboard creates a new keyboard builder with the specified payload encoding
 // type and maximum number of buttons per row.
 //
-// Use NewInlineKeyboardJson or NewInlineKeyboardBase64 for the common cases.
+// Use NewInlineKeyboardJSON or NewInlineKeyboardBase64 for the common cases.
 func NewInlineKeyboard(payloadType BotPayloadType, maxRow int) *InlineKeyboard {
 	return &InlineKeyboard{
 		CurrentLine: make(extypes.Slice[tgapi.InlineKeyboardButton], 0),
@@ -136,15 +184,27 @@ func NewInlineKeyboard(payloadType BotPayloadType, maxRow int) *InlineKeyboard {
 	}
 }
 
-// SetPayloadType sets the serialization format for callback data added via
+// SetPayloadType sets the keyboard-local serialization format for callback data added via
 // AddCallbackButton and AddCallbackButtonStyle methods.
-// It should be one of BotPayloadJson or BotPayloadBase64.
+// It overrides the bot's default payload type for this keyboard only.
 func (in *InlineKeyboard) SetPayloadType(t BotPayloadType) *InlineKeyboard {
 	in.payloadType = t
 	return in
 }
 
-// Internal helper that appends a button and auto-flushes a full row.
+// GetPayloadType returns the keyboard-local callback payload encoding type.
+func (in *InlineKeyboard) GetPayloadType() BotPayloadType { return in.payloadType }
+
+// SetMaxRow sets the maximum number of buttons appended to a row before the
+// keyboard automatically starts a new line.
+func (in *InlineKeyboard) SetMaxRow(maxRow int) *InlineKeyboard {
+	in.maxRow = maxRow
+	return in
+}
+
+// GetMaxRow returns the maximum number of buttons per row.
+func (in *InlineKeyboard) GetMaxRow() int { return in.maxRow }
+
 func (in *InlineKeyboard) append(button tgapi.InlineKeyboardButton) *InlineKeyboard {
 	if in.CurrentLine.Len() == in.maxRow {
 		in.AddLine()
@@ -153,21 +213,21 @@ func (in *InlineKeyboard) append(button tgapi.InlineKeyboardButton) *InlineKeybo
 	return in
 }
 
-// AddUrlButton adds a button that opens a URL when pressed.
+// AddURLButton adds a button that opens a URL when pressed.
 // No callback data is attached.
-func (in *InlineKeyboard) AddUrlButton(text, url string) *InlineKeyboard {
+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.
+// 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 {
+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 according to the current payloadType.
-func (in *InlineKeyboard) AddCallbackButton(text string, cmd string, args ...any) *InlineKeyboard {
+func (in *InlineKeyboard) AddCallbackButton(text, cmd string, args ...any) *InlineKeyboard {
 	return in.append(tgapi.InlineKeyboardButton{
 		Text:         text,
 		CallbackData: NewCallbackData(cmd, args...).Encode(in.payloadType),
@@ -184,9 +244,9 @@ func (in *InlineKeyboard) AddCallbackButtonStyle(text string, style tgapi.Keyboa
 	})
 }
 
-// AddButton adds a button pre-configured via InlineKbButtonBuilder.
+// AddButton adds a button pre-configured via InlineKeyboardButtonBuilder.
 // This is the most flexible way to create buttons with custom emoji, style, URL, and callback.
-func (in *InlineKeyboard) AddButton(b InlineKbButtonBuilder) *InlineKeyboard {
+func (in *InlineKeyboard) AddButton(b InlineKeyboardButtonBuilder) *InlineKeyboard {
 	return in.append(b.build())
 }
 
@@ -243,18 +303,18 @@ func NewCallbackData(command string, args ...any) CallbackData {
 	}
 }
 
-// ToJson serializes the CallbackData to a JSON string.
+// All To* encoders return an empty string when serialization fails. Telegram
-//
+// rejects empty callback_data, so an empty result surfaces a real bug rather
-// If serialization fails (e.g., due to unmarshalable fields), returns a fallback
+// than masking it with a stub payload that silently routes to no handler.
-// JSON object: {"cmd":""} to prevent breaking Telegram's API.
+// Build CallbackData from primitives (string, []string) only — the encoders
-//
+// have no failure modes for that input.
-// This fallback ensures the bot receives a valid JSON payload even if internal
+
-// errors occur — avoiding "invalid callback_data" errors from Telegram.
+// ToJSON serializes the CallbackData to a JSON string.
-func (d CallbackData) ToJson() string {
+// Returns an empty string if serialization fails.
-	data, err := encodeJsonPayload(d)
+func (d CallbackData) ToJSON() string {
+	data, err := encodeJSONPayload(d)
 	if err != nil {
-		// Fallback: return minimal valid JSON to avoid Telegram API rejection
+		return ""
-		return `{"cmd":""}`
 	}
 	return data
 }
@@ -262,22 +322,50 @@ func (d CallbackData) ToJson() string {
 // ToBase64 serializes the CallbackData to a JSON string and then encodes it as Base64.
 // Returns an empty string if serialization or encoding fails.
 func (d CallbackData) ToBase64() string {
-	s, err := encodeBase64Payload(d)
+	data, err := encodeBase64Payload(d)
 	if err != nil {
-		return ``
+		return ""
 	}
-	return s
+	return data
+}
+
+// ToCompact serializes the CallbackData to a compact delimited string.
+// Returns an empty string if serialization fails.
+//
+// The compact format coalesces "no args" with "single empty arg" — both
+// produce "cmd|" and decode back to nil args. Use ToJSON or ToBase64 when
+// that distinction must be preserved.
+func (d CallbackData) ToCompact() string {
+	data, err := encodeCompactPayload(d)
+	if err != nil {
+		return ""
+	}
+	return data
+}
+
+// ToCompactBase64 serializes the CallbackData to compact text and then encodes it as Base64.
+// Returns an empty string if serialization or encoding fails.
+func (d CallbackData) ToCompactBase64() string {
+	data, err := encodeCompactBase64Payload(d)
+	if err != nil {
+		return ""
+	}
+	return data
 }
 
 // Encode serializes the CallbackData according to the specified payload type.
-// Supported types: BotPayloadJson and BotPayloadBase64.
+// Supported types: BotPayloadJSON, BotPayloadBase64, BotPayloadCompact, and BotPayloadCompactBase64.
 // For unknown types, returns an empty string.
 func (d CallbackData) Encode(t BotPayloadType) string {
 	switch t {
 	case BotPayloadBase64:
 		return d.ToBase64()
-	case BotPayloadJson:
+	case BotPayloadJSON:
-		return d.ToJson()
+		return d.ToJSON()
+	case BotPayloadCompact:
+		return d.ToCompact()
+	case BotPayloadCompactBase64:
+		return d.ToCompactBase64()
 	}
 	return ""
 }

keyboard_test.go

@@ -1,12 +1,14 @@
 package laniakea
 
 import (
+	"errors"
+	"reflect"
 	"strings"
 	"testing"
 )
 
 func TestInlineKeyboardWrapsRowsAndEncodesJSONPayloads(t *testing.T) {
-	kb := NewInlineKeyboardJson(2).
+	kb := NewInlineKeyboardJSON(2).
 		AddCallbackButton("A", "cmd", 1).
 		AddCallbackButton("B", "cmd", 2).
 		AddCallbackButton("C", "cmd", 3)
@@ -29,9 +31,9 @@ func TestInlineKeyboardWrapsRowsAndEncodesJSONPayloads(t *testing.T) {
 func TestInlineKeyboardBuilderPreservesConfiguredButtonFields(t *testing.T) {
 	kb := NewInlineKeyboardBase64(3).
 		AddButton(
-			NewInlineKbButton("Docs").
+			NewInlineKeyboardButton("Docs").
 				SetStyle(ButtonStylePrimary).
-				SetUrl("https://example.test"),
+				SetURL("https://example.test"),
 		)
 
 	button := kb.Get().InlineKeyboard[0][0]
@@ -42,3 +44,182 @@ func TestInlineKeyboardBuilderPreservesConfiguredButtonFields(t *testing.T) {
 		t.Fatalf("unexpected url: %q", button.URL)
 	}
 }
+
+func TestInlineKeyboardButtonBuilderSetCallbackDataDefaultsToJSON(t *testing.T) {
+	kb := NewInlineKeyboardBase64(1).
+		AddButton(NewInlineKeyboardButton("A").SetCallbackData("cmd", 1, "two"))
+
+	button := kb.Get().InlineKeyboard[0][0]
+	if !strings.Contains(button.CallbackData, `"cmd":"cmd"`) {
+		t.Fatalf("expected JSON callback payload, got %q", button.CallbackData)
+	}
+}
+
+func TestInlineKeyboardButtonBuilderSetCallbackDataUsesConfiguredPayloadType(t *testing.T) {
+	kb := NewInlineKeyboardJSON(1).
+		AddButton(NewInlineKeyboardButton("A").
+			SetPayloadType(BotPayloadBase64).
+			SetCallbackData("cmd", 1, "two"),
+		)
+
+	got, _, err := decodePayload(BotPayloadJSON, kb.Get().InlineKeyboard[0][0].CallbackData, false)
+	if err != nil {
+		t.Fatalf("decodePayload returned error: %v", err)
+	}
+
+	want := CallbackData{Command: "cmd", Args: []string{"1", "two"}}
+	if !reflect.DeepEqual(got, want) {
+		t.Fatalf("unexpected payload: got %#v want %#v", got, want)
+	}
+}
+
+func TestInlineKeyboardGetPayloadTypeReturnsLocalOverride(t *testing.T) {
+	kb := NewInlineKeyboardJSON(2)
+	if got := kb.GetPayloadType(); got != BotPayloadJSON {
+		t.Fatalf("unexpected initial payload type: %q", got)
+	}
+	kb.SetPayloadType(BotPayloadBase64)
+	if got := kb.GetPayloadType(); got != BotPayloadBase64 {
+		t.Fatalf("unexpected updated payload type: %q", got)
+	}
+}
+
+func TestDecodePayloadAcceptsBase64KeyboardPayloadWhenBotPrefersJSON(t *testing.T) {
+	kb := NewInlineKeyboardBase64(1).
+		AddCallbackButton("A", "cmd", 1, "two")
+
+	got, _, err := decodePayload(BotPayloadJSON, kb.Get().InlineKeyboard[0][0].CallbackData, false)
+	if err != nil {
+		t.Fatalf("decodePayload returned error: %v", err)
+	}
+
+	want := CallbackData{Command: "cmd", Args: []string{"1", "two"}}
+	if !reflect.DeepEqual(got, want) {
+		t.Fatalf("unexpected payload: got %#v want %#v", got, want)
+	}
+}
+
+func TestDecodePayloadAcceptsJSONKeyboardPayloadWhenBotPrefersBase64(t *testing.T) {
+	kb := NewInlineKeyboardJSON(1).
+		AddCallbackButton("A", "cmd", 1, "two")
+
+	got, _, err := decodePayload(BotPayloadBase64, kb.Get().InlineKeyboard[0][0].CallbackData, false)
+	if err != nil {
+		t.Fatalf("decodePayload returned error: %v", err)
+	}
+
+	want := CallbackData{Command: "cmd", Args: []string{"1", "two"}}
+	if !reflect.DeepEqual(got, want) {
+		t.Fatalf("unexpected payload: got %#v want %#v", got, want)
+	}
+}
+
+func TestDecodePayloadAcceptsCompactKeyboardPayloadWhenBotPrefersJSON(t *testing.T) {
+	kb := NewInlineKeyboardCompact(1).
+		AddCallbackButton("A", "cmd", 1, "two")
+
+	got, decodedType, err := decodePayload(BotPayloadJSON, kb.Get().InlineKeyboard[0][0].CallbackData, false)
+	if err != nil {
+		t.Fatalf("decodePayload returned error: %v", err)
+	}
+	if decodedType != BotPayloadCompact {
+		t.Fatalf("unexpected decoded payload type: got %q want %q", decodedType, BotPayloadCompact)
+	}
+
+	want := CallbackData{Command: "cmd", Args: []string{"1", "two"}}
+	if !reflect.DeepEqual(got, want) {
+		t.Fatalf("unexpected payload: got %#v want %#v", got, want)
+	}
+}
+
+func TestDecodePayloadAcceptsCompactBase64KeyboardPayloadWhenBotPrefersJSON(t *testing.T) {
+	kb := NewInlineKeyboardCompactBase64(1).
+		AddCallbackButton("A", "cmd", 1, "two")
+
+	got, decodedType, err := decodePayload(BotPayloadJSON, kb.Get().InlineKeyboard[0][0].CallbackData, false)
+	if err != nil {
+		t.Fatalf("decodePayload returned error: %v", err)
+	}
+	if decodedType != BotPayloadCompactBase64 {
+		t.Fatalf("unexpected decoded payload type: got %q want %q", decodedType, BotPayloadCompactBase64)
+	}
+
+	want := CallbackData{Command: "cmd", Args: []string{"1", "two"}}
+	if !reflect.DeepEqual(got, want) {
+		t.Fatalf("unexpected payload: got %#v want %#v", got, want)
+	}
+}
+
+// TestCompactPayloadRoundTripsWithSeparatorChars guards the compact-encoding
+// escape fix. Args containing the , | or \ separator bytes previously corrupted
+// on decode; now they must round-trip exactly.
+//
+// Note: the compact format coalesces "no args" with "single empty arg" — both
+// emit "cmd|" and decode to nil args. Use other encodings if that distinction
+// matters.
+func TestCompactPayloadRoundTripsWithSeparatorChars(t *testing.T) {
+	tests := []struct {
+		name string
+		data CallbackData
+	}{
+		{name: "plain", data: CallbackData{Command: "cmd", Args: []string{"one", "two"}}},
+		{name: "no args", data: CallbackData{Command: "cmd"}},
+		{name: "comma in arg", data: CallbackData{Command: "cmd", Args: []string{"a,b", "c"}}},
+		{name: "pipe in arg", data: CallbackData{Command: "cmd", Args: []string{"a|b", "c"}}},
+		{name: "backslash in arg", data: CallbackData{Command: "cmd", Args: []string{`a\b`, "c"}}},
+		{name: "all specials in arg", data: CallbackData{Command: "cmd", Args: []string{`a,b|c\d`}}},
+		{name: "specials in command", data: CallbackData{Command: "a|b,c", Args: []string{"x"}}},
+		{name: "two empty args", data: CallbackData{Command: "cmd", Args: []string{"", ""}}},
+		{name: "utf8 args", data: CallbackData{Command: "cmd", Args: []string{"привет", "мир"}}},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			encoded, err := encodeCompactPayload(tt.data)
+			if err != nil {
+				t.Fatalf("encodeCompactPayload returned error: %v", err)
+			}
+			got, err := decodeCompactPayload(encoded)
+			if err != nil {
+				t.Fatalf("decodeCompactPayload returned error: %v", err)
+			}
+			if got.Command != tt.data.Command {
+				t.Fatalf("command mismatch: got %q want %q (encoded=%q)", got.Command, tt.data.Command, encoded)
+			}
+			if len(got.Args) != len(tt.data.Args) {
+				t.Fatalf("args length mismatch: got %v want %v (encoded=%q)", got.Args, tt.data.Args, encoded)
+			}
+			for i := range tt.data.Args {
+				if got.Args[i] != tt.data.Args[i] {
+					t.Fatalf("arg %d mismatch: got %q want %q (encoded=%q)", i, got.Args[i], tt.data.Args[i], encoded)
+				}
+			}
+		})
+	}
+}
+
+func TestCompactPayloadDecodeRejectsMissingSeparator(t *testing.T) {
+	if _, err := decodeCompactPayload("noseparator"); err == nil {
+		t.Fatal("expected error decoding payload without separator")
+	}
+}
+
+func TestDecodePayloadStrictRejectsCompactMismatchedType(t *testing.T) {
+	kb := NewInlineKeyboardCompact(1).
+		AddCallbackButton("A", "cmd", 1)
+
+	_, _, err := decodePayload(BotPayloadJSON, kb.Get().InlineKeyboard[0][0].CallbackData, true)
+	if !errors.Is(err, ErrPayloadTypeMismatch) {
+		t.Fatalf("expected ErrPayloadTypeMismatch, got %v", err)
+	}
+}
+
+func TestDecodePayloadStrictRejectsMismatchedType(t *testing.T) {
+	kb := NewInlineKeyboardBase64(1).
+		AddCallbackButton("A", "cmd", 1)
+
+	_, _, err := decodePayload(BotPayloadJSON, kb.Get().InlineKeyboard[0][0].CallbackData, true)
+	if !errors.Is(err, ErrPayloadTypeMismatch) {
+		t.Fatalf("expected ErrPayloadTypeMismatch, got %v", err)
+	}
+}

methods.go

@@ -3,8 +3,9 @@ package laniakea
 import (
 	"context"
 	"encoding/json"
+	"iter"
 
-	"git.nix13.pw/scuroneko/laniakea/tgapi"
+	"git.scuroneko.dev/scuroneko/laniakea/tgapi"
 )
 
 // Updates fetches new updates from Telegram API using long polling.
@@ -21,15 +22,15 @@ import (
 //
 // Behavior:
 //  1. Uses the bot's current update offset (via GetUpdateOffset)
-//  2. Requests updates with 30-second timeout
+//  2. Requests updates with the timeout configured via PollTimeout
 //  3. Filters updates by types specified in bot.GetUpdateTypes()
 //  4. Logs raw update JSON if RequestLogger is configured
 //  5. Automatically updates the offset to the last received update ID + 1
 //  6. Returns all received updates (empty slice if none)
 //
-// Note: This is a blocking call that waits up to 30 seconds for new updates,
+// Note: This is a blocking call that waits up to the configured PollTimeout
-// unless ctx is canceled earlier. For non-blocking behavior, consider using
+// for new updates, unless ctx is canceled earlier. For non-blocking behavior,
-// webhooks instead.
+// consider using webhooks instead.
 //
 // Example:
 //
@@ -42,28 +43,52 @@ import (
 //	}
 func (bot *Bot[T]) Updates(ctx context.Context) ([]tgapi.Update, error) {
 	offset := bot.GetUpdateOffset()
+	timeout := bot.pollTimeout
 	params := tgapi.UpdateParams{
-		Offset:         Ptr(offset),
+		Offset:         new(offset),
-		Timeout:        Ptr(30),
+		Timeout:        new(timeout),
 		AllowedUpdates: bot.GetUpdateTypes(),
 	}
 
+	zero := make([]tgapi.Update, 0)
 	updates, err := bot.api.GetUpdatesWithContext(ctx, params)
 	if err != nil {
-		return nil, err
+		return zero, err
 	}
 
-	if bot.RequestLogger != nil {
+	if bot.requestLogger != nil {
 		for _, u := range updates {
 			j, err := json.Marshal(u)
 			if err != nil {
 				bot.GetLogger().Error(err)
 			}
-			bot.RequestLogger.Debugf("UPDATE %s\n", j)
+			bot.requestLogger.Debugf("UPDATE %s\n", j)
 		}
 	}
 	if len(updates) > 0 {
 		bot.SetUpdateOffset(updates[len(updates)-1].UpdateID + 1)
 	}
-	return updates, err
+	if updates == nil {
+		return zero, nil
+	}
+	return updates, nil
+}
+
+// UpdatesIter fetches updates once and yields each update in order.
+//
+// If fetching updates fails, the iterator yields the error once with a zero
+// update and then stops.
+func (bot *Bot[T]) UpdatesIter(ctx context.Context) iter.Seq2[tgapi.Update, error] {
+	return func(yield func(tgapi.Update, error) bool) {
+		updates, err := bot.Updates(ctx)
+		if err != nil {
+			yield(tgapi.Update{}, err)
+			return
+		}
+		for _, u := range updates {
+			if !yield(u, nil) {
+				return
+			}
+		}
+	}
 }

methods_test.go

@@ -0,0 +1,78 @@
+package laniakea
+
+import (
+	"context"
+	"io"
+	"net/http"
+	"strings"
+	"testing"
+
+	"git.scuroneko.dev/scuroneko/laniakea/tgapi"
+)
+
+func TestUpdatesIterYieldsFetchError(t *testing.T) {
+	bot := newUpdatesIterTestBot(t, `{"ok":false,"error_code":500,"description":"boom"}`)
+
+	var gotErr error
+	var gotUpdates int
+	bot.UpdatesIter(context.Background())(func(update tgapi.Update, err error) bool {
+		gotUpdates++
+		if update.UpdateID != 0 {
+			t.Fatalf("expected zero update on error, got %d", update.UpdateID)
+		}
+		gotErr = err
+		return true
+	})
+
+	if gotUpdates != 1 {
+		t.Fatalf("expected one yielded error, got %d yields", gotUpdates)
+	}
+	if gotErr == nil {
+		t.Fatal("expected fetch error")
+	}
+	if !strings.Contains(gotErr.Error(), "boom") {
+		t.Fatalf("expected Telegram error description, got %v", gotErr)
+	}
+}
+
+func TestUpdatesIterStopsWhenYieldReturnsFalse(t *testing.T) {
+	bot := newUpdatesIterTestBot(t, `{"ok":true,"result":[{"update_id":11},{"update_id":12}]}`)
+
+	var gotIDs []int
+	bot.UpdatesIter(context.Background())(func(update tgapi.Update, err error) bool {
+		if err != nil {
+			t.Fatalf("unexpected error: %v", err)
+		}
+		gotIDs = append(gotIDs, update.UpdateID)
+		return false
+	})
+
+	if len(gotIDs) != 1 || gotIDs[0] != 11 {
+		t.Fatalf("expected only first update, got %v", gotIDs)
+	}
+}
+
+func newUpdatesIterTestBot(t *testing.T, response string) *Bot[NoData] {
+	t.Helper()
+
+	api := tgapi.NewAPI(
+		tgapi.NewAPIOpts("token").
+			SetAPIURL("https://example.test").
+			SetHTTPClient(&http.Client{
+				Transport: pollingRoundTripFunc(func(req *http.Request) (*http.Response, error) {
+					return &http.Response{
+						StatusCode: http.StatusOK,
+						Header:     http.Header{"Content-Type": []string{"application/json"}},
+						Body:       io.NopCloser(strings.NewReader(response)),
+					}, nil
+				}),
+			}),
+	)
+	t.Cleanup(func() {
+		if err := api.Close(); err != nil {
+			t.Fatalf("Close returned error: %v", err)
+		}
+	})
+
+	return &Bot[NoData]{api: api}
+}

msg_context.go

@@ -2,75 +2,127 @@ package laniakea
 
 import (
 	"context"
+	"errors"
 	"fmt"
+	"log"
+	"reflect"
+	"strconv"
+	"strings"
 	"time"
 
-	"git.nix13.pw/scuroneko/laniakea/tgapi"
+	"git.scuroneko.dev/scuroneko/laniakea/tgapi"
-	"git.nix13.pw/scuroneko/slog"
+	"git.scuroneko.dev/scuroneko/sneklog/v2"
 )
 
-// MsgContext holds the context for handling a Telegram message or callback query.
+// MessageContext holds the normalized per-update context passed to command, payload,
-// It provides methods to respond, edit, delete, and translate messages, as well as
+// scene, middleware, and generic update handlers.
-// manage inline keyboards and message drafts.
+//
-type MsgContext struct {
+// MessageContext is populated from the current Telegram update before handler routing.
-	Api    *tgapi.API
+// Not every field is guaranteed for every update kind. In particular:
+//   - Update is always present.
+//   - Msg is populated only for update kinds that carry a Telegram message object.
+//   - From and FromID are populated only when the update exposes a user identity.
+//   - Chat and ChatID are populated only when the update exposes a chat identity.
+//   - Text, Args, and Prefix are populated only by command or scene command routing.
+//   - CallbackQueryID, CallbackMsgID, and InlineMsgID are populated only for
+//     callback query handling when the corresponding callback targets exist.
+//
+// Helper methods on MessageContext may require a message-backed context. For example,
+// reply helpers need Msg, while inline callback edit helpers can work through
+// InlineMsgID when there is no chat message.
+type MessageContext struct {
+	API    *tgapi.API
 	Update tgapi.Update
 
-	Msg  *tgapi.Message
+	// Msg is the normalized Telegram message for message-backed update kinds.
+	// It is nil for updates that do not include a message object.
+	Msg *tgapi.Message
+	// From is the normalized Telegram user for update kinds that expose one.
+	// It stays nil for sender-chat-only updates and update kinds without a user.
 	From *tgapi.User
+	// Chat is the normalized Telegram chat for update kinds that expose one.
+	// It is nil for updates that do not include a chat identity.
+	Chat *tgapi.Chat
 
 	// Logger is the logger assigned by the matched plugin for the current handler call.
 	// It may fall back to the bot logger when the plugin has no dedicated logger.
-	Logger *slog.Logger
+	Logger *sneklog.Logger
 
-	InlineMsgId     string
+	// InlineMsgID is the inline message identifier for callback queries that target
-	CallbackMsgId   int
+	// an inline message instead of a chat message.
-	CallbackQueryId string
+	InlineMsgID string
-	FromID          int64
+	// CallbackMsgID is the message ID targeted by the current callback query when
-	Prefix          string
+	// the callback comes from a chat message.
-	Text            string
+	CallbackMsgID int
-	Args            []string
+	// CallbackQueryID is the Telegram callback query ID for payload handlers and
+	// callback-backed scene handlers.
+	CallbackQueryID string
+	// FromID is the normalized sender ID when the current update exposes a user.
+	// It is zero when the update has no user identity.
+	FromID int64
+	// ChatID is the normalized chat ID when the current update exposes a chat.
+	// It is zero when the update has no chat identity.
+	ChatID int64
+	// Prefix is the matched command prefix for command routing and scene-local
+	// command routing. It is empty outside those flows.
+	Prefix string
+	// Text is the parsed command tail for command routing, the parsed scene-command
+	// tail for scene-local command routing, or the trimmed message text seen by a
+	// scene step/message handler. It is empty when the current routing path does
+	// not derive text input.
+	Text string
+	// Args contains parsed command or payload arguments for the current routing
+	// path. It is nil or empty when no argument vector is derived.
+	Args []string
 
 	errorTemplate string
 	l10n          *L10n
 	draftProvider *DraftProvider
 	payloadType   BotPayloadType
+	sceneRuntime  sceneRuntime
+	observer      Observer
+	botID         int64
+
+	ctx context.Context
 }
 
-// AnswerMessage represents a message sent or edited via MsgContext.
+// AnswerMessage represents a message sent or edited via MessageContext.
 // It holds metadata to allow further editing or deletion.
 type AnswerMessage struct {
 	MessageID int
 	Text      string
 	IsMedia   bool
-	ctx       *MsgContext // internal back-reference
+	ctx       *MessageContext // internal back-reference
 }
 
-// Internal helper for text edits with optional keyboard and parse mode.
+func (ctx *MessageContext) edit(messageID int, text string, keyboard *InlineKeyboard, parseMode tgapi.ParseMode) *AnswerMessage {
-func (ctx *MsgContext) edit(messageId int, text string, keyboard *InlineKeyboard, parseMode tgapi.ParseMode) *AnswerMessage {
+	if err := validateMessageText(text); err != nil {
-	params := tgapi.EditMessageTextP{
+		ctx.Logger.Errorln(err)
+		return nil
+	}
+	params := tgapi.EditMessageText{
 		Text:      text,
 		ParseMode: parseMode,
 	}
 	switch {
-	case messageId > 0 && ctx.Msg != nil:
+	case messageID > 0 && ctx.Msg != nil:
-		params.MessageID = messageId
+		params.MessageID = messageID
 		params.ChatID = ctx.Msg.Chat.ID
-	case ctx.InlineMsgId != "":
+	case ctx.InlineMsgID != "":
-		params.InlineMessageID = ctx.InlineMsgId
+		params.InlineMessageID = ctx.InlineMsgID
 	default:
-		ctx.Logger.Errorln("Can't edit message: no valid message target")
+		ctx.Logger.Errorln(ErrEditTargetMissing)
 		return nil
 	}
 	if keyboard != nil {
 		params.ReplyMarkup = keyboard.Get()
 	}
-	msg, _, err := ctx.Api.EditMessageText(params)
+	msg, _, err := ctx.API.EditMessageTextWithContext(ctx.Context(), params)
 	if err != nil {
 		ctx.Logger.Errorln(err)
 		return nil
 	}
-	resultMessageID := messageId
+	resultMessageID := messageID
 	if msg.MessageID > 0 {
 		resultMessageID = msg.MessageID
 	}
@@ -87,71 +139,73 @@ func (m *AnswerMessage) Edit(text string) *AnswerMessage {
 
 // EditMarkdown replaces the text of the message using MarkdownV2 formatting.
 //
-// ⚠️ WARNING: User input must be escaped with laniakea.EscapeMarkdownV2() before passing here.
+// ⚠️ WARNING: User input must be escaped with tgfmt.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)
+	return m.ctx.edit(m.MessageID, text, nil, tgapi.ParseMarkdownV2)
 }
 
-// Internal helper for editing callback-linked messages.
+func (ctx *MessageContext) editCallback(text string, keyboard *InlineKeyboard, parseMode tgapi.ParseMode) *AnswerMessage {
-func (ctx *MsgContext) editCallback(text string, keyboard *InlineKeyboard, parseMode tgapi.ParseMode) *AnswerMessage {
+	if ctx.CallbackMsgID == 0 && ctx.InlineMsgID == "" {
-	if ctx.CallbackMsgId == 0 && ctx.InlineMsgId == "" {
+		ctx.Logger.Errorln(ErrCallbackMessageMissing)
-		ctx.Logger.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, parseMode)
 }
 
 // EditCallback edits the callback message using plain text (ParseNone).
-func (ctx *MsgContext) EditCallback(text string, keyboard *InlineKeyboard) *AnswerMessage {
+func (ctx *MessageContext) 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.
+// ⚠️ WARNING: User input must be escaped with tgfmt.EscapeMarkdownV2() before passing here.
-func (ctx *MsgContext) EditCallbackMarkdown(text string, keyboard *InlineKeyboard) *AnswerMessage {
+func (ctx *MessageContext) EditCallbackMarkdown(text string, keyboard *InlineKeyboard) *AnswerMessage {
-	return ctx.editCallback(text, keyboard, tgapi.ParseMDV2)
+	return ctx.editCallback(text, keyboard, tgapi.ParseMarkdownV2)
 }
 
 // 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 {
+func (ctx *MessageContext) EditCallbackf(format string, keyboard *InlineKeyboard, args ...any) *AnswerMessage {
 	return ctx.editCallback(fmt.Sprintf(format, args...), keyboard, tgapi.ParseNone)
 }
 
 // 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.
+// ⚠️ WARNING: User input must be escaped with tgfmt.EscapeMarkdownV2() before passing here.
-func (ctx *MsgContext) EditCallbackfMarkdown(format string, keyboard *InlineKeyboard, args ...any) *AnswerMessage {
+func (ctx *MessageContext) EditCallbackfMarkdown(format string, keyboard *InlineKeyboard, args ...any) *AnswerMessage {
-	return ctx.editCallback(fmt.Sprintf(format, args...), keyboard, tgapi.ParseMDV2)
+	return ctx.editCallback(fmt.Sprintf(format, args...), keyboard, tgapi.ParseMarkdownV2)
 }
 
-// Internal helper for media-caption edits.
+func (ctx *MessageContext) editPhotoText(messageID int, text string, kb *InlineKeyboard, parseMode tgapi.ParseMode) *AnswerMessage {
-func (ctx *MsgContext) editPhotoText(messageId int, text string, kb *InlineKeyboard, parseMode tgapi.ParseMode) *AnswerMessage {
+	if err := validateCaptionText(text); err != nil {
-	params := tgapi.EditMessageCaptionP{
+		ctx.Logger.Errorln(err)
+		return nil
+	}
+	params := tgapi.EditMessageCaption{
 		Caption:   text,
 		ParseMode: parseMode,
 	}
 	switch {
-	case messageId > 0 && ctx.Msg != nil:
+	case messageID > 0 && ctx.Msg != nil:
 		params.ChatID = ctx.Msg.Chat.ID
-		params.MessageID = messageId
+		params.MessageID = messageID
-	case ctx.InlineMsgId != "":
+	case ctx.InlineMsgID != "":
-		params.InlineMessageID = ctx.InlineMsgId
+		params.InlineMessageID = ctx.InlineMsgID
 	default:
-		ctx.Logger.Errorln("Can't edit caption: no valid message target")
+		ctx.Logger.Errorln(ErrEditTargetMissing)
 		return nil
 	}
 	if kb != nil {
 		params.ReplyMarkup = kb.Get()
 	}
 
-	msg, _, err := ctx.Api.EditMessageCaption(params)
+	msg, _, err := ctx.API.EditMessageCaptionWithContext(ctx.Context(), params)
 	if err != nil {
 		ctx.Logger.Errorln(err)
 		return nil
 	}
-	resultMessageID := messageId
+	resultMessageID := messageID
 	if msg.MessageID > 0 {
 		resultMessageID = msg.MessageID
 	}
@@ -167,9 +221,9 @@ func (m *AnswerMessage) EditCaption(text string) *AnswerMessage {
 
 // EditCaptionMarkdown edits the caption of a media message using MarkdownV2.
 //
-// ⚠️ WARNING: User input must be escaped with laniakea.EscapeMarkdownV2() before passing here.
+// ⚠️ WARNING: User input must be escaped with tgfmt.EscapeMarkdownV2() before passing here.
 func (m *AnswerMessage) EditCaptionMarkdown(text string) *AnswerMessage {
-	return m.ctx.editPhotoText(m.MessageID, text, nil, tgapi.ParseMDV2)
+	return m.ctx.editPhotoText(m.MessageID, text, nil, tgapi.ParseMarkdownV2)
 }
 
 // EditCaptionKeyboard edits the caption of a media message with a new inline keyboard (plain text).
@@ -179,18 +233,21 @@ func (m *AnswerMessage) EditCaptionKeyboard(text string, kb *InlineKeyboard) *An
 
 // 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.
+// ⚠️ WARNING: User input must be escaped with tgfmt.EscapeMarkdownV2() before passing here.
 func (m *AnswerMessage) EditCaptionKeyboardMarkdown(text string, kb *InlineKeyboard) *AnswerMessage {
-	return m.ctx.editPhotoText(m.MessageID, text, kb, tgapi.ParseMDV2)
+	return m.ctx.editPhotoText(m.MessageID, text, kb, tgapi.ParseMarkdownV2)
 }
 
-// Internal helper for message replies with optional keyboard and parse mode.
+func (ctx *MessageContext) answer(text string, keyboard *InlineKeyboard, parseMode tgapi.ParseMode) *AnswerMessage {
-func (ctx *MsgContext) answer(text string, keyboard *InlineKeyboard, parseMode tgapi.ParseMode) *AnswerMessage {
 	if ctx.Msg == nil {
-		ctx.Logger.Errorln("Can't answer message without a message")
+		ctx.Logger.Errorln(ErrMessageContextNil)
 		return nil
 	}
-	params := tgapi.SendMessageP{
+	if err := validateMessageText(text); err != nil {
+		ctx.Logger.Errorln(err)
+		return nil
+	}
+	params := tgapi.SendMessage{
 		ChatID:    ctx.Msg.Chat.ID,
 		Text:      text,
 		ParseMode: parseMode,
@@ -205,7 +262,7 @@ func (ctx *MsgContext) answer(text string, keyboard *InlineKeyboard, parseMode t
 		params.DirectMessagesTopicID = ctx.Msg.DirectMessageTopic.TopicID
 	}
 
-	msg, err := ctx.Api.SendMessage(params)
+	msg, err := ctx.API.SendMessageWithContext(ctx.Context(), params)
 	if err != nil {
 		ctx.Logger.Errorln(err)
 		return nil
@@ -216,52 +273,114 @@ func (ctx *MsgContext) answer(text string, keyboard *InlineKeyboard, parseMode t
 }
 
 // Answer sends a plain text message (ParseNone).
-func (ctx *MsgContext) Answer(text string) *AnswerMessage {
+func (ctx *MessageContext) Answer(text string) *AnswerMessage {
 	return ctx.answer(text, nil, tgapi.ParseNone)
 }
 
+// AnswerLong sends one or more plain-text messages if text exceeds Telegram's limit.
+//
+// The text is split into Telegram-safe chunks. Returned messages preserve send
+// order. If a chunk fails to send, already-sent messages are returned.
+func (ctx *MessageContext) AnswerLong(text string) []*AnswerMessage {
+	return ctx.answerLong(text, nil, tgapi.ParseNone)
+}
+
 // AnswerMarkdown sends a message using MarkdownV2 formatting.
 //
-// ⚠️ WARNING: User input must be escaped with laniakea.EscapeMarkdownV2() before passing here.
+// ⚠️ WARNING: User input must be escaped with tgfmt.EscapeMarkdownV2() before passing here.
-func (ctx *MsgContext) AnswerMarkdown(text string) *AnswerMessage {
+func (ctx *MessageContext) AnswerMarkdown(text string) *AnswerMessage {
-	return ctx.answer(text, nil, tgapi.ParseMDV2)
+	return ctx.answer(text, nil, tgapi.ParseMarkdownV2)
 }
 
 // Answerf formats a string using fmt.Sprintf and sends it as a plain text message.
-func (ctx *MsgContext) Answerf(template string, args ...any) *AnswerMessage {
+func (ctx *MessageContext) Answerf(template string, args ...any) *AnswerMessage {
 	return ctx.answer(fmt.Sprintf(template, args...), nil, tgapi.ParseNone)
 }
 
+// AnswerLongf formats a string using fmt.Sprintf and sends it as one or more plain-text messages.
+func (ctx *MessageContext) AnswerLongf(template string, args ...any) []*AnswerMessage {
+	return ctx.answerLong(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.
+// ⚠️ WARNING: User input must be escaped with tgfmt.EscapeMarkdownV2() before passing here.
-func (ctx *MsgContext) AnswerfMarkdown(template string, args ...any) *AnswerMessage {
+func (ctx *MessageContext) AnswerfMarkdown(template string, args ...any) *AnswerMessage {
-	return ctx.answer(fmt.Sprintf(template, args...), nil, tgapi.ParseMDV2)
+	return ctx.answer(fmt.Sprintf(template, args...), nil, tgapi.ParseMarkdownV2)
 }
 
 // Keyboard sends a message with an inline keyboard (plain text).
-func (ctx *MsgContext) Keyboard(text string, kb *InlineKeyboard) *AnswerMessage {
+func (ctx *MessageContext) Keyboard(text string, kb *InlineKeyboard) *AnswerMessage {
 	return ctx.answer(text, kb, tgapi.ParseNone)
 }
 
+// KeyboardLong sends long plain text split across multiple messages.
+//
+// The inline keyboard is attached only to the final chunk.
+func (ctx *MessageContext) KeyboardLong(text string, kb *InlineKeyboard) []*AnswerMessage {
+	return ctx.answerLong(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.
+// ⚠️ WARNING: User input must be escaped with tgfmt.EscapeMarkdownV2() before passing here.
-func (ctx *MsgContext) KeyboardMarkdown(text string, keyboard *InlineKeyboard) *AnswerMessage {
+func (ctx *MessageContext) KeyboardMarkdown(text string, keyboard *InlineKeyboard) *AnswerMessage {
-	return ctx.answer(text, keyboard, tgapi.ParseMDV2)
+	return ctx.answer(text, keyboard, tgapi.ParseMarkdownV2)
 }
 
-// Internal helper for photo replies with optional caption and keyboard.
+func (ctx *MessageContext) answerLong(text string, keyboard *InlineKeyboard, parseMode tgapi.ParseMode) []*AnswerMessage {
-func (ctx *MsgContext) answerPhoto(photoId, text string, kb *InlineKeyboard, parseMode tgapi.ParseMode) *AnswerMessage {
+	if parseMode != tgapi.ParseNone {
-	if ctx.Msg == nil {
+		ctx.Logger.Errorln(ErrMessageSplitImpossible)
-		ctx.Logger.Errorln("Can't answer message without a message")
 		return nil
 	}
-	params := tgapi.SendPhotoP{
+	if ctx.Msg == nil {
+		ctx.Logger.Errorln(ErrMessageContextNil)
+		return nil
+	}
+	if err := validateMessageText(text); err == nil {
+		msg := ctx.answer(text, keyboard, parseMode)
+		if msg == nil {
+			return nil
+		}
+		return []*AnswerMessage{msg}
+	} else if !errors.Is(err, ErrMessageTooLong) {
+		ctx.Logger.Errorln(err)
+		return nil
+	}
+
+	parts := SplitMessageText(text)
+	messages := make([]*AnswerMessage, 0, len(parts))
+	for i, part := range parts {
+		partKeyboard := (*InlineKeyboard)(nil)
+		if i == len(parts)-1 {
+			partKeyboard = keyboard
+		}
+		msg := ctx.answer(part, partKeyboard, parseMode)
+		if msg == nil {
+			break
+		}
+		messages = append(messages, msg)
+	}
+	if len(messages) == 0 {
+		return nil
+	}
+	return messages
+}
+
+func (ctx *MessageContext) answerPhoto(photoID, text string, kb *InlineKeyboard, parseMode tgapi.ParseMode) *AnswerMessage {
+	if ctx.Msg == nil {
+		ctx.Logger.Errorln(ErrMessageContextNil)
+		return nil
+	}
+	if err := validateCaptionText(text); err != nil {
+		ctx.Logger.Errorln(err)
+		return nil
+	}
+	params := tgapi.SendPhoto{
 		ChatID:    ctx.Msg.Chat.ID,
 		Caption:   text,
 		ParseMode: parseMode,
-		Photo:     photoId,
+		Photo:     photoID,
 	}
 	if kb != nil {
 		params.ReplyMarkup = kb.Get()
@@ -273,7 +392,7 @@ func (ctx *MsgContext) answerPhoto(photoId, text string, kb *InlineKeyboard, par
 		params.DirectMessagesTopicID = int(ctx.Msg.DirectMessageTopic.TopicID)
 	}
 
-	msg, err := ctx.Api.SendPhoto(params)
+	msg, err := ctx.API.SendPhotoWithContext(ctx.Context(), params)
 	if err != nil {
 		ctx.Logger.Errorln(err)
 		return nil
@@ -284,54 +403,53 @@ func (ctx *MsgContext) answerPhoto(photoId, text string, kb *InlineKeyboard, par
 }
 
 // AnswerPhoto sends a photo with plain text caption.
-func (ctx *MsgContext) AnswerPhoto(photoId, text string) *AnswerMessage {
+func (ctx *MessageContext) AnswerPhoto(photoID, text string) *AnswerMessage {
-	return ctx.answerPhoto(photoId, text, nil, tgapi.ParseNone)
+	return ctx.answerPhoto(photoID, text, nil, tgapi.ParseNone)
 }
 
 // AnswerPhotoMarkdown sends a photo with MarkdownV2 caption.
 //
-// ⚠️ WARNING: User input must be escaped with laniakea.EscapeMarkdownV2() before passing here.
+// ⚠️ WARNING: User input must be escaped with tgfmt.EscapeMarkdownV2() before passing here.
-func (ctx *MsgContext) AnswerPhotoMarkdown(photoId, text string) *AnswerMessage {
+func (ctx *MessageContext) AnswerPhotoMarkdown(photoID, text string) *AnswerMessage {
-	return ctx.answerPhoto(photoId, text, nil, tgapi.ParseMDV2)
+	return ctx.answerPhoto(photoID, text, nil, tgapi.ParseMarkdownV2)
 }
 
 // AnswerPhotoKeyboard sends a photo with caption and inline keyboard (plain text).
-func (ctx *MsgContext) AnswerPhotoKeyboard(photoId, text string, kb *InlineKeyboard) *AnswerMessage {
+func (ctx *MessageContext) AnswerPhotoKeyboard(photoID, text string, kb *InlineKeyboard) *AnswerMessage {
-	return ctx.answerPhoto(photoId, text, kb, tgapi.ParseNone)
+	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.
+// ⚠️ WARNING: User input must be escaped with tgfmt.EscapeMarkdownV2() before passing here.
-func (ctx *MsgContext) AnswerPhotoKeyboardMarkdown(photoId, text string, kb *InlineKeyboard) *AnswerMessage {
+func (ctx *MessageContext) AnswerPhotoKeyboardMarkdown(photoID, text string, kb *InlineKeyboard) *AnswerMessage {
-	return ctx.answerPhoto(photoId, text, kb, tgapi.ParseMDV2)
+	return ctx.answerPhoto(photoID, text, kb, tgapi.ParseMarkdownV2)
 }
 
 // AnswerPhotof formats a string and sends it as a photo caption (plain text).
-func (ctx *MsgContext) AnswerPhotof(photoId, template string, args ...any) *AnswerMessage {
+func (ctx *MessageContext) AnswerPhotof(photoID, template string, args ...any) *AnswerMessage {
-	return ctx.answerPhoto(photoId, fmt.Sprintf(template, args...), nil, tgapi.ParseNone)
+	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.
+// ⚠️ WARNING: User input must be escaped with tgfmt.EscapeMarkdownV2() before passing here.
-func (ctx *MsgContext) AnswerPhotofMarkdown(photoId, template string, args ...any) *AnswerMessage {
+func (ctx *MessageContext) AnswerPhotofMarkdown(photoID, template string, args ...any) *AnswerMessage {
-	return ctx.answerPhoto(photoId, fmt.Sprintf(template, args...), nil, tgapi.ParseMDV2)
+	return ctx.answerPhoto(photoID, fmt.Sprintf(template, args...), nil, tgapi.ParseMarkdownV2)
 }
 
-// Internal helper that deletes a message by ID.
+func (ctx *MessageContext) delete(messageID int) {
-func (ctx *MsgContext) delete(messageId int) {
+	if messageID == 0 {
-	if messageId == 0 {
+		ctx.Logger.Errorln(ErrMessageIDZero)
-		ctx.Logger.Errorln("Can't delete message: message ID zero")
 		return
 	}
 	if ctx.Msg == nil {
-		ctx.Logger.Errorln("Can't delete message: no chat message context")
+		ctx.Logger.Errorln(ErrMessageContextNil)
 		return
 	}
-	_, err := ctx.Api.DeleteMessage(tgapi.DeleteMessageP{
+	_, err := ctx.API.DeleteMessageWithContext(ctx.Context(), tgapi.DeleteMessage{
 		ChatID:    ctx.Msg.Chat.ID,
-		MessageID: messageId,
+		MessageID: messageID,
 	})
 	if err != nil {
 		ctx.Logger.Errorln(err)
@@ -342,21 +460,20 @@ func (ctx *MsgContext) delete(messageId int) {
 func (m *AnswerMessage) Delete() { m.ctx.delete(m.MessageID) }
 
 // CallbackDelete deletes the message that triggered the callback query.
-func (ctx *MsgContext) CallbackDelete() {
+func (ctx *MessageContext) CallbackDelete() {
-	if ctx.CallbackMsgId == 0 {
+	if ctx.CallbackMsgID == 0 {
-		ctx.Logger.Errorln("Can't delete callback message: no callback message ID")
+		ctx.Logger.Errorln(ErrCallbackMessageMissing)
 		return
 	}
-	ctx.delete(ctx.CallbackMsgId)
+	ctx.delete(ctx.CallbackMsgID)
 }
 
-// Internal helper that answers a callback query with optional text, alert, or URL.
+func (ctx *MessageContext) answerCallbackQuery(url, text string, showAlert bool) {
-func (ctx *MsgContext) answerCallbackQuery(url, text string, showAlert bool) {
+	if len(ctx.CallbackQueryID) == 0 {
-	if len(ctx.CallbackQueryId) == 0 {
 		return
 	}
-	_, err := ctx.Api.AnswerCallbackQuery(tgapi.AnswerCallbackQueryP{
+	_, err := ctx.API.AnswerCallbackQueryWithContext(ctx.Context(), tgapi.AnswerCallbackQuery{
-		CallbackQueryID: ctx.CallbackQueryId,
+		CallbackQueryID: ctx.CallbackQueryID,
 		Text:            text, ShowAlert: showAlert, URL: url,
 	})
 	if err != nil {
@@ -364,69 +481,79 @@ func (ctx *MsgContext) answerCallbackQuery(url, text string, showAlert bool) {
 	}
 }
 
-// AnswerCbQuery answers the callback query with no text or alert.
+// AnswerCallback answers the callback query with no text or alert.
-func (ctx *MsgContext) AnswerCbQuery() { ctx.answerCallbackQuery("", "", false) }
+func (ctx *MessageContext) AnswerCallback() { ctx.answerCallbackQuery("", "", false) }
 
-// AnswerCbQueryText answers the callback query with a text notification.
+// AnswerCallbackText answers the callback query with a text notification.
-func (ctx *MsgContext) AnswerCbQueryText(text string) { ctx.answerCallbackQuery("", text, false) }
+func (ctx *MessageContext) AnswerCallbackText(text string) { ctx.answerCallbackQuery("", text, false) }
 
-// AnswerCbQueryAlert answers the callback query with a user-visible alert.
+// AnswerCallbackAlert answers the callback query with a user-visible alert.
-func (ctx *MsgContext) AnswerCbQueryAlert(text string) { ctx.answerCallbackQuery("", text, true) }
+func (ctx *MessageContext) AnswerCallbackAlert(text string) { ctx.answerCallbackQuery("", text, true) }
 
-// AnswerCbQueryUrl answers the callback query with a URL redirect.
+// AnswerCallbackURL answers the callback query with a URL redirect.
-func (ctx *MsgContext) AnswerCbQueryUrl(u string) { ctx.answerCallbackQuery(u, "", false) }
+func (ctx *MessageContext) AnswerCallbackURL(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) {
+func (ctx *MessageContext) SendAction(action tgapi.ChatActionType) {
 	if ctx.Msg == nil {
-		ctx.Logger.Errorln("Can't send action without chat message context")
+		ctx.Logger.Errorln(ErrMessageContextNil)
 		return
 	}
-	params := tgapi.SendChatActionP{
+	params := tgapi.SendChatAction{
 		ChatID: ctx.Msg.Chat.ID, Action: action,
 	}
 	if ctx.Msg.MessageThreadID > 0 {
 		params.MessageThreadID = ctx.Msg.MessageThreadID
 	}
-	_, err := ctx.Api.SendChatAction(params)
+	_, err := ctx.API.SendChatActionWithContext(ctx.Context(), params)
 	if err != nil {
 		ctx.Logger.Errorln(err)
 	}
 }
 
-// Internal helper that formats, sends, and logs an error.
+func (ctx *MessageContext) error(err error) {
-func (ctx *MsgContext) error(err error) {
+	if err == nil {
+		return
+	}
+	ctx.Logger.Errorln(err)
+	if !IsUserError(err) {
+		return
+	}
 	text := fmt.Sprintf(ctx.errorTemplate, err.Error())
 
-	if ctx.CallbackQueryId != "" {
+	if ctx.CallbackQueryID != "" {
 		ctx.answerCallbackQuery("", text, false)
 	} else {
 		ctx.answer(text, nil, tgapi.ParseNone)
 	}
-	ctx.Logger.Errorln(err)
 }
 
-// Error is an alias for error().
+// Error routes err through the centralized handler error path.
-func (ctx *MsgContext) Error(err error) { ctx.error(err) }
+//
+// The error is logged via ctx.Logger. When IsUserError(err) is true, the
+// formatted error template is delivered to the user — through an answer
+// to the active callback query when one exists, otherwise as a chat reply.
+// Internal errors are logged but not surfaced to the user.
+func (ctx *MessageContext) Error(err error) { ctx.error(err) }
 
-func (ctx *MsgContext) newDraft(parseMode tgapi.ParseMode) *Draft {
+func (ctx *MessageContext) newDraft(parseMode tgapi.ParseMode) *Draft {
 	if ctx.Msg == nil {
-		ctx.Logger.Errorln("can't create draft: ctx.Msg is nil")
+		ctx.Logger.Errorln(ErrMessageContextNil)
 		return nil
 	}
-	if ctx.Api == nil {
+	if ctx.API == nil {
-		ctx.Logger.Errorln("can't create draft: ctx.Api is nil")
+		ctx.Logger.Errorln(ErrAPIIsNil)
 		return nil
 	}
 	if ctx.draftProvider == nil {
-		ctx.Logger.Errorln("can't create draft: ctx.draftProvider is nil")
+		ctx.Logger.Errorln(ErrDraftProviderNil)
 		return nil
 	}
 
-	if ctx.Api.Limiter != nil {
+	if ctx.API.Limiter != nil {
-		c, cancel := context.WithTimeout(context.Background(), 5*time.Second)
+		c, cancel := context.WithTimeout(ctx.Context(), 5*time.Second)
 		defer cancel()
-		if err := ctx.Api.Limiter.Wait(c, ctx.Msg.Chat.ID); err != nil {
+		if err := ctx.API.Limiter.Wait(c, ctx.Msg.Chat.ID); err != nil {
 			ctx.Logger.Errorln(err)
 			return nil
 		}
@@ -438,20 +565,20 @@ func (ctx *MsgContext) newDraft(parseMode tgapi.ParseMode) *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 {
+func (ctx *MessageContext) NewDraft() *Draft {
 	return ctx.newDraft(tgapi.ParseNone)
 }
 
 // NewDraftMarkdown creates a new message draft associated with the current chat,
 // with Markdown V2 parse mode enabled.
 // Uses the API limiter to avoid rate limiting.
-func (ctx *MsgContext) NewDraftMarkdown() *Draft {
+func (ctx *MessageContext) NewDraftMarkdown() *Draft {
-	return ctx.newDraft(tgapi.ParseMDV2)
+	return ctx.newDraft(tgapi.ParseMarkdownV2)
 }
 
 // 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 {
+func (ctx *MessageContext) Translate(key string) string {
 	if ctx.From == nil {
 		return key
 	}
@@ -461,6 +588,236 @@ func (ctx *MsgContext) Translate(key string) string {
 
 // NewInlineKeyboard creates a new keyboard builder with the context's payload
 // encoding type and the specified maximum number of buttons per row.
-func (ctx *MsgContext) NewInlineKeyboard(maxRow int) *InlineKeyboard {
+func (ctx *MessageContext) NewInlineKeyboard(maxRow int) *InlineKeyboard {
 	return NewInlineKeyboard(ctx.payloadType, maxRow)
 }
+
+// NewInlineKeyboardButton creates a button builder using the context payload encoding.
+func (ctx *MessageContext) NewInlineKeyboardButton(text string) InlineKeyboardButtonBuilder {
+	return NewInlineKeyboardButton(text).SetPayloadType(ctx.payloadType)
+}
+
+func bindPositional(args []string, dst any) error {
+	v := reflect.ValueOf(dst)
+	if v.Kind() != reflect.Pointer || v.IsNil() {
+		return ErrBindArgsTargetNotPointer
+	}
+
+	v = v.Elem()
+	if v.Kind() != reflect.Struct {
+		return ErrBindArgsTargetNotStruct
+	}
+
+	t := v.Type()
+	fields := make([]int, 0, v.NumField())
+
+	for i := 0; i < v.NumField(); i++ {
+		field := v.Field(i)
+		if !field.CanSet() {
+			continue
+		}
+		fields = append(fields, i)
+	}
+
+	argIndex := 0
+	for fieldPos, fieldIndex := range fields {
+		field := v.Field(fieldIndex)
+		fieldType := t.Field(fieldIndex)
+
+		if argIndex >= len(args) {
+			// Leave trailing fields at their zero values when arguments run out.
+			break
+		}
+
+		isLastBindableField := fieldPos == len(fields)-1
+
+		raw := args[argIndex]
+		if isLastBindableField && field.Kind() == reflect.String {
+			raw = strings.Join(args[argIndex:], " ")
+		}
+
+		switch field.Kind() {
+		case reflect.String:
+			field.SetString(raw)
+		case reflect.Int, reflect.Int8, reflect.Int16, reflect.Int32, reflect.Int64:
+			n, err := strconv.ParseInt(raw, 10, 64)
+			if err != nil {
+				return fmt.Errorf("%w: field %s: %v", ErrBindArgsConversion, fieldType.Name, err)
+			}
+			field.SetInt(n)
+		case reflect.Uint, reflect.Uint8, reflect.Uint16, reflect.Uint32, reflect.Uint64:
+			n, err := strconv.ParseUint(raw, 10, 64)
+			if err != nil {
+				return fmt.Errorf("%w: field %s: %v", ErrBindArgsConversion, fieldType.Name, err)
+			}
+			field.SetUint(n)
+		case reflect.Float32, reflect.Float64:
+			f, err := strconv.ParseFloat(raw, 64)
+			if err != nil {
+				return fmt.Errorf("%w: field %s: %v", ErrBindArgsConversion, fieldType.Name, err)
+			}
+			field.SetFloat(f)
+		case reflect.Bool:
+			b, err := strconv.ParseBool(raw)
+			if err != nil {
+				return fmt.Errorf("%w: field %s: %v", ErrBindArgsConversion, fieldType.Name, err)
+			}
+			field.SetBool(b)
+		default:
+			return fmt.Errorf("%w: field %s: %s", ErrBindArgsUnsupportedFieldType, fieldType.Name, field.Kind())
+		}
+
+		if isLastBindableField && field.Kind() == reflect.String {
+			break
+		}
+		argIndex++
+	}
+
+	return nil
+}
+
+// BindArgs binds positional command arguments from ctx.Args into dst.
+//
+// Exported struct fields are filled in declaration order. When fewer arguments
+// are provided than fields, the remaining fields keep their zero values. If the
+// final bindable field is a string, it receives the remaining arguments joined
+// with spaces.
+func (ctx *MessageContext) BindArgs(dst any) error {
+	return bindPositional(ctx.Args, dst)
+}
+
+// Context returns the request-scoped context associated with the current update.
+func (ctx *MessageContext) Context() context.Context {
+	if ctx.ctx == nil {
+		return context.Background()
+	}
+	return ctx.ctx
+}
+
+func (ctx *MessageContext) emitPolicyChecked(event PolicyCheckedEvent) {
+	if ctx == nil || ctx.observer == nil {
+		return
+	}
+	defer func() {
+		if r := recover(); r != nil {
+			if ctx.Logger != nil {
+				ctx.Logger.Errorln(fmt.Sprintf("panic in observer policy event: %v", r))
+				return
+			}
+			log.Printf("panic in observer policy event: %v", r)
+		}
+	}()
+	ctx.observer.OnPolicyChecked(ctx.Context(), event)
+}
+
+// EnterScene enters the named scene at its configured entry step.
+func (ctx *MessageContext) EnterScene(name string) error {
+	if ctx.sceneRuntime == nil {
+		return ErrSceneRuntimeNil
+	}
+
+	scene, ok := ctx.sceneRuntime.findScene(name)
+	if !ok {
+		return ErrSceneNotFound
+	}
+
+	key, ok := buildSceneKey(scene.Scope, ctx)
+	if !ok {
+		return ErrCantFindSession
+	}
+	if scene.Entry == "" {
+		return ErrSceneEntryNotSet
+	}
+	if _, ok := scene.Steps[scene.Entry]; !ok {
+		return ErrSceneStepNotFound
+	}
+
+	session := SceneSession{
+		Scene: scene.Name,
+		Step:  scene.Entry,
+	}
+
+	return ctx.sceneRuntime.setSession(key, session)
+}
+
+// EnterSceneStep enters the named scene at a specific step.
+func (ctx *MessageContext) EnterSceneStep(name, step string) error {
+	if ctx.sceneRuntime == nil {
+		return ErrSceneRuntimeNil
+	}
+
+	scene, ok := ctx.sceneRuntime.findScene(name)
+	if !ok {
+		return ErrSceneNotFound
+	}
+	if _, ok := scene.Steps[step]; !ok {
+		return ErrSceneStepNotFound
+	}
+
+	key, ok := buildSceneKey(scene.Scope, ctx)
+	if !ok {
+		return ErrCantFindSession
+	}
+
+	session := SceneSession{Scene: scene.Name, Step: step}
+
+	return ctx.sceneRuntime.setSession(key, session)
+}
+
+// ExitScene leaves the currently active scene for this context.
+func (ctx *MessageContext) ExitScene() error {
+	if ctx.sceneRuntime == nil {
+		return ErrSceneRuntimeNil
+	}
+
+	_, session, err := ctx.sceneRuntime.findSceneSession(ctx)
+	if err != nil {
+		return err
+	}
+	if session.Scene == "" {
+		return ErrNotInScene
+	}
+
+	scene, ok := ctx.sceneRuntime.findScene(session.Scene)
+	if !ok {
+		return ErrSceneNotFound
+	}
+
+	key, ok := buildSceneKey(scene.Scope, ctx)
+	if !ok {
+		return ErrCantFindSession
+	}
+
+	return ctx.sceneRuntime.deleteSession(key)
+}
+
+// IsCallback reports whether the context belongs to a callback query.
+func (ctx *MessageContext) IsCallback() bool {
+	return ctx.CallbackQueryID != "" || ctx.CallbackMsgID > 0 || ctx.InlineMsgID != ""
+}
+
+// HasPhoto reports whether the current message contains a photo payload.
+func (ctx *MessageContext) HasPhoto() bool {
+	return ctx.Msg != nil && ctx.Msg.Photo.Len() > 0
+}
+
+func (ctx *MessageContext) upsertKeyboard(text string, keyboard *InlineKeyboard, parseMode tgapi.ParseMode) *AnswerMessage {
+	if ctx.IsCallback() {
+		if ctx.HasPhoto() {
+			ctx.CallbackDelete()
+			return ctx.answer(text, keyboard, parseMode)
+		}
+		return ctx.editCallback(text, keyboard, parseMode)
+	}
+	return ctx.answer(text, keyboard, parseMode)
+}
+
+// UpsertKeyboard edits a callback message or sends a new plain-text message with a keyboard.
+func (ctx *MessageContext) UpsertKeyboard(text string, keyboard *InlineKeyboard) *AnswerMessage {
+	return ctx.upsertKeyboard(text, keyboard, tgapi.ParseNone)
+}
+
+// UpsertKeyboardMarkdown edits a callback message or sends a new MarkdownV2 message with a keyboard.
+func (ctx *MessageContext) UpsertKeyboardMarkdown(text string, keyboard *InlineKeyboard) *AnswerMessage {
+	return ctx.upsertKeyboard(text, keyboard, tgapi.ParseMarkdownV2)
+}

msg_context_test.go

@@ -2,13 +2,15 @@ package laniakea
 
 import (
 	"encoding/json"
+	"errors"
 	"io"
 	"net/http"
+	"reflect"
 	"strings"
 	"testing"
 
-	"git.nix13.pw/scuroneko/laniakea/tgapi"
+	"git.scuroneko.dev/scuroneko/laniakea/tgapi"
-	"git.nix13.pw/scuroneko/slog"
+	"git.scuroneko.dev/scuroneko/sneklog/v2"
 )
 
 func TestAnswerPhotoIncludesDirectMessagesTopicID(t *testing.T) {
@@ -33,7 +35,7 @@ func TestAnswerPhotoIncludesDirectMessagesTopicID(t *testing.T) {
 
 	api := tgapi.NewAPI(
 		tgapi.NewAPIOpts("token").
-			SetAPIUrl("https://example.test").
+			SetAPIURL("https://example.test").
 			SetHTTPClient(client),
 	)
 	defer func() {
@@ -42,18 +44,19 @@ func TestAnswerPhotoIncludesDirectMessagesTopicID(t *testing.T) {
 		}
 	}()
 
-	ctx := &MsgContext{
+	ctx := &MessageContext{
-		Api: api,
+		API: api,
 		Msg: &tgapi.Message{
-			Chat:               &tgapi.Chat{ID: 42, Type: string(tgapi.ChatTypePrivate)},
+			Chat:               &tgapi.Chat{ID: 42, Type: tgapi.ChatTypePrivate},
 			DirectMessageTopic: &tgapi.DirectMessageTopic{TopicID: 77},
 		},
-		Logger: slog.CreateLogger(),
+		Logger: sneklog.NewLogger(),
 	}
 
 	answer := ctx.AnswerPhoto("photo-id", "caption")
 	if answer == nil {
 		t.Fatal("expected answer message")
+		return
 	}
 	if answer.MessageID != 9 {
 		t.Fatalf("unexpected message id: %d", answer.MessageID)
@@ -62,3 +65,536 @@ func TestAnswerPhotoIncludesDirectMessagesTopicID(t *testing.T) {
 		t.Fatalf("unexpected direct_messages_topic_id: %v", got)
 	}
 }
+
+func TestBindArgsBindsScalarFields(t *testing.T) {
+	type input struct {
+		ID     int
+		Active bool
+		Score  float64
+		Name   string
+	}
+
+	ctx := &MessageContext{Args: []string{"42", "true", "3.5", "Ada", "Lovelace"}}
+	var got input
+
+	if err := ctx.BindArgs(&got); err != nil {
+		t.Fatalf("BindArgs returned error: %v", err)
+	}
+
+	want := input{
+		ID:     42,
+		Active: true,
+		Score:  3.5,
+		Name:   "Ada Lovelace",
+	}
+	if !reflect.DeepEqual(got, want) {
+		t.Fatalf("unexpected bound value: got %#v want %#v", got, want)
+	}
+}
+
+func TestNewInlineKeyboardButtonUsesContextPayloadType(t *testing.T) {
+	ctx := &MessageContext{payloadType: BotPayloadBase64}
+
+	kb := NewInlineKeyboardJSON(1).
+		AddButton(ctx.NewInlineKeyboardButton("A").SetCallbackData("cmd", 1, "two"))
+
+	got, _, err := decodePayload(BotPayloadJSON, kb.Get().InlineKeyboard[0][0].CallbackData, false)
+	if err != nil {
+		t.Fatalf("decodePayload returned error: %v", err)
+	}
+
+	want := CallbackData{Command: "cmd", Args: []string{"1", "two"}}
+	if !reflect.DeepEqual(got, want) {
+		t.Fatalf("unexpected payload: got %#v want %#v", got, want)
+	}
+}
+
+func TestBindArgsLeavesTrailingFieldsZeroWhenArgsRunOut(t *testing.T) {
+	type input struct {
+		ID     int
+		Reason string
+		Admin  bool
+	}
+
+	ctx := &MessageContext{Args: []string{"7"}}
+	var got input
+
+	if err := ctx.BindArgs(&got); err != nil {
+		t.Fatalf("BindArgs returned error: %v", err)
+	}
+
+	if got.ID != 7 {
+		t.Fatalf("unexpected ID: got %d want 7", got.ID)
+	}
+	if got.Reason != "" {
+		t.Fatalf("expected zero-value Reason, got %q", got.Reason)
+	}
+	if got.Admin {
+		t.Fatal("expected zero-value Admin")
+	}
+}
+
+func TestBindArgsRejectsInvalidTargets(t *testing.T) {
+	ctx := &MessageContext{Args: []string{"1"}}
+
+	if err := ctx.BindArgs(nil); !errors.Is(err, ErrBindArgsTargetNotPointer) {
+		t.Fatalf("expected ErrBindArgsTargetNotPointer for nil target, got %v", err)
+	}
+
+	var notStruct int
+	if err := ctx.BindArgs(&notStruct); !errors.Is(err, ErrBindArgsTargetNotStruct) {
+		t.Fatalf("expected ErrBindArgsTargetNotStruct for non-struct target, got %v", err)
+	}
+}
+
+func TestBindArgsReportsConversionFailures(t *testing.T) {
+	type input struct {
+		ID int
+	}
+
+	ctx := &MessageContext{Args: []string{"oops"}}
+	var got input
+
+	err := ctx.BindArgs(&got)
+	if err == nil {
+		t.Fatal("expected BindArgs to fail")
+	}
+	if !errors.Is(err, ErrBindArgsConversion) {
+		t.Fatalf("expected ErrBindArgsConversion, got %v", err)
+	}
+	if !strings.Contains(err.Error(), "field ID") {
+		t.Fatalf("expected field name in error, got %v", err)
+	}
+}
+
+func TestBindArgsRejectsUnsupportedFieldTypes(t *testing.T) {
+	type input struct {
+		Tags []string
+	}
+
+	ctx := &MessageContext{Args: []string{"tag"}}
+	var got input
+
+	err := ctx.BindArgs(&got)
+	if err == nil {
+		t.Fatal("expected BindArgs to fail")
+	}
+	if !errors.Is(err, ErrBindArgsUnsupportedFieldType) {
+		t.Fatalf("expected ErrBindArgsUnsupportedFieldType, got %v", err)
+	}
+}
+
+func TestErrorDefaultStaysInternalForMessageFlow(t *testing.T) {
+	client := &http.Client{
+		Transport: roundTripFunc(func(req *http.Request) (*http.Response, error) {
+			t.Fatal("unexpected HTTP request for unclassified error")
+			return nil, nil
+		}),
+	}
+
+	api := tgapi.NewAPI(
+		tgapi.NewAPIOpts("token").
+			SetAPIURL("https://example.test").
+			SetHTTPClient(client),
+	)
+	defer func() {
+		if err := api.Close(); err != nil {
+			t.Fatalf("Close returned error: %v", err)
+		}
+	}()
+
+	ctx := &MessageContext{
+		API:           api,
+		Msg:           &tgapi.Message{Chat: &tgapi.Chat{ID: 42, Type: tgapi.ChatTypePrivate}},
+		Logger:        sneklog.NewLogger(),
+		errorTemplate: "Error: %s",
+	}
+
+	// Unclassified errors must not leak to the user. Only AsUserError replies.
+	ctx.error(errors.New("boom"))
+}
+
+func TestErrorUserVisibleAnswersForMessageFlow(t *testing.T) {
+	var requests int
+	var gotBody map[string]any
+
+	client := &http.Client{
+		Transport: roundTripFunc(func(req *http.Request) (*http.Response, error) {
+			requests++
+			body, err := io.ReadAll(req.Body)
+			if err != nil {
+				t.Fatalf("failed to read request body: %v", err)
+			}
+			if err := json.Unmarshal(body, &gotBody); err != nil {
+				t.Fatalf("failed to decode request body: %v", err)
+			}
+			return &http.Response{
+				StatusCode: http.StatusOK,
+				Header:     http.Header{"Content-Type": []string{"application/json"}},
+				Body:       io.NopCloser(strings.NewReader(`{"ok":true,"result":{"message_id":9,"date":1}}`)),
+			}, nil
+		}),
+	}
+
+	api := tgapi.NewAPI(
+		tgapi.NewAPIOpts("token").
+			SetAPIURL("https://example.test").
+			SetHTTPClient(client),
+	)
+	defer func() {
+		if err := api.Close(); err != nil {
+			t.Fatalf("Close returned error: %v", err)
+		}
+	}()
+
+	ctx := &MessageContext{
+		API:           api,
+		Msg:           &tgapi.Message{Chat: &tgapi.Chat{ID: 42, Type: tgapi.ChatTypePrivate}},
+		Logger:        sneklog.NewLogger(),
+		errorTemplate: "Error: %s",
+	}
+
+	ctx.error(AsUserError(errors.New("boom")))
+
+	if requests != 1 {
+		t.Fatalf("expected one user-facing error reply, got %d requests", requests)
+	}
+	if got := gotBody["text"]; got != "Error: boom" {
+		t.Fatalf("unexpected error reply text: %v", got)
+	}
+}
+
+func TestErrorInternalSkipsUserReplyForMessageFlow(t *testing.T) {
+	client := &http.Client{
+		Transport: roundTripFunc(func(req *http.Request) (*http.Response, error) {
+			t.Fatal("unexpected HTTP request for internal-only error")
+			return nil, nil
+		}),
+	}
+
+	api := tgapi.NewAPI(
+		tgapi.NewAPIOpts("token").
+			SetAPIURL("https://example.test").
+			SetHTTPClient(client),
+	)
+	defer func() {
+		if err := api.Close(); err != nil {
+			t.Fatalf("Close returned error: %v", err)
+		}
+	}()
+
+	ctx := &MessageContext{
+		API:           api,
+		Msg:           &tgapi.Message{Chat: &tgapi.Chat{ID: 42, Type: tgapi.ChatTypePrivate}},
+		Logger:        sneklog.NewLogger(),
+		errorTemplate: "Error: %s",
+	}
+
+	ctx.error(AsInternalError(errors.New("boom")))
+}
+
+func TestErrorInternalSkipsCallbackAnswer(t *testing.T) {
+	client := &http.Client{
+		Transport: roundTripFunc(func(req *http.Request) (*http.Response, error) {
+			t.Fatal("unexpected callback answer request for internal-only error")
+			return nil, nil
+		}),
+	}
+
+	api := tgapi.NewAPI(
+		tgapi.NewAPIOpts("token").
+			SetAPIURL("https://example.test").
+			SetHTTPClient(client),
+	)
+	defer func() {
+		if err := api.Close(); err != nil {
+			t.Fatalf("Close returned error: %v", err)
+		}
+	}()
+
+	ctx := &MessageContext{
+		API:             api,
+		Logger:          sneklog.NewLogger(),
+		errorTemplate:   "%s",
+		CallbackQueryID: "cb-1",
+	}
+
+	ctx.error(AsInternalError(errors.New("boom")))
+}
+
+func TestErrorUserVisibleAnswersCallback(t *testing.T) {
+	var requests int
+	var gotBody map[string]any
+
+	client := &http.Client{
+		Transport: roundTripFunc(func(req *http.Request) (*http.Response, error) {
+			requests++
+			body, err := io.ReadAll(req.Body)
+			if err != nil {
+				t.Fatalf("failed to read request body: %v", err)
+			}
+			if err := json.Unmarshal(body, &gotBody); err != nil {
+				t.Fatalf("failed to decode request body: %v", err)
+			}
+			return &http.Response{
+				StatusCode: http.StatusOK,
+				Header:     http.Header{"Content-Type": []string{"application/json"}},
+				Body:       io.NopCloser(strings.NewReader(`{"ok":true,"result":true}`)),
+			}, nil
+		}),
+	}
+
+	api := tgapi.NewAPI(
+		tgapi.NewAPIOpts("token").
+			SetAPIURL("https://example.test").
+			SetHTTPClient(client),
+	)
+	defer func() {
+		if err := api.Close(); err != nil {
+			t.Fatalf("Close returned error: %v", err)
+		}
+	}()
+
+	ctx := &MessageContext{
+		API:             api,
+		Logger:          sneklog.NewLogger(),
+		errorTemplate:   "Oops: %s",
+		CallbackQueryID: "cb-1",
+	}
+
+	ctx.error(AsUserError(errors.New("boom")))
+
+	if requests != 1 {
+		t.Fatalf("expected one callback error answer, got %d requests", requests)
+	}
+	if got := gotBody["text"]; got != "Oops: boom" {
+		t.Fatalf("unexpected callback error text: %v", got)
+	}
+}
+
+func TestIsCallbackIncludesInlineCallbackTargets(t *testing.T) {
+	tests := []struct {
+		name string
+		ctx  MessageContext
+		want bool
+	}{
+		{name: "callback query id", ctx: MessageContext{CallbackQueryID: "cb-1"}, want: true},
+		{name: "callback message id", ctx: MessageContext{CallbackMsgID: 12}, want: true},
+		{name: "inline message id", ctx: MessageContext{InlineMsgID: "inline-1"}, want: true},
+		{name: "not callback", ctx: MessageContext{}, want: false},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			if got := tt.ctx.IsCallback(); got != tt.want {
+				t.Fatalf("IsCallback() = %v, want %v", got, tt.want)
+			}
+		})
+	}
+}
+
+func TestUpsertKeyboardEditsInlineCallback(t *testing.T) {
+	var requests int
+	var gotPath string
+	var gotBody map[string]any
+
+	client := &http.Client{
+		Transport: roundTripFunc(func(req *http.Request) (*http.Response, error) {
+			requests++
+			gotPath = req.URL.Path
+			body, err := io.ReadAll(req.Body)
+			if err != nil {
+				t.Fatalf("failed to read request body: %v", err)
+			}
+			if err := json.Unmarshal(body, &gotBody); err != nil {
+				t.Fatalf("failed to decode request body: %v", err)
+			}
+			return &http.Response{
+				StatusCode: http.StatusOK,
+				Header:     http.Header{"Content-Type": []string{"application/json"}},
+				Body:       io.NopCloser(strings.NewReader(`{"ok":true,"result":true}`)),
+			}, nil
+		}),
+	}
+
+	api := tgapi.NewAPI(
+		tgapi.NewAPIOpts("token").
+			SetAPIURL("https://example.test").
+			SetHTTPClient(client),
+	)
+	defer func() {
+		if err := api.Close(); err != nil {
+			t.Fatalf("Close returned error: %v", err)
+		}
+	}()
+
+	ctx := &MessageContext{
+		API:         api,
+		InlineMsgID: "inline-1",
+		Logger:      sneklog.NewLogger(),
+	}
+	kb := NewInlineKeyboardJSON(1).AddCallbackButton("A", "cmd")
+
+	answer := ctx.UpsertKeyboard("updated", kb)
+	if answer == nil {
+		t.Fatal("expected answer message")
+	}
+	if requests != 1 {
+		t.Fatalf("expected one edit request, got %d", requests)
+	}
+	if gotPath != "/bottoken/editMessageText" {
+		t.Fatalf("unexpected request path: %s", gotPath)
+	}
+	if got := gotBody["inline_message_id"]; got != "inline-1" {
+		t.Fatalf("unexpected inline_message_id: %v", got)
+	}
+	if got := gotBody["text"]; got != "updated" {
+		t.Fatalf("unexpected text: %v", got)
+	}
+	if _, ok := gotBody["reply_markup"]; !ok {
+		t.Fatal("expected reply_markup in edit request")
+	}
+}
+
+func TestAnswerRejectsEmptyMessage(t *testing.T) {
+	ctx := &MessageContext{
+		Msg:    &tgapi.Message{Chat: &tgapi.Chat{ID: 42, Type: tgapi.ChatTypePrivate}},
+		Logger: sneklog.NewLogger(),
+	}
+
+	if answer := ctx.Answer(""); answer != nil {
+		t.Fatal("expected nil answer for empty message")
+	}
+}
+
+func TestAnswerRejectsLongMessageWithoutSendingRequest(t *testing.T) {
+	client := &http.Client{
+		Transport: roundTripFunc(func(req *http.Request) (*http.Response, error) {
+			t.Fatal("unexpected HTTP request")
+			return nil, nil
+		}),
+	}
+
+	api := tgapi.NewAPI(
+		tgapi.NewAPIOpts("token").
+			SetAPIURL("https://example.test").
+			SetHTTPClient(client),
+	)
+	defer func() {
+		if err := api.Close(); err != nil {
+			t.Fatalf("Close returned error: %v", err)
+		}
+	}()
+
+	ctx := &MessageContext{
+		API:    api,
+		Msg:    &tgapi.Message{Chat: &tgapi.Chat{ID: 42, Type: tgapi.ChatTypePrivate}},
+		Logger: sneklog.NewLogger(),
+	}
+
+	if answer := ctx.Answer(strings.Repeat("a", maxMessageTextLen+1)); answer != nil {
+		t.Fatal("expected nil answer for long message")
+	}
+}
+
+func TestValidateMessageText(t *testing.T) {
+	if err := validateMessageText(""); !errors.Is(err, ErrEmptyMessage) {
+		t.Fatalf("expected ErrEmptyMessage, got %v", err)
+	}
+	if err := validateMessageText(strings.Repeat("a", maxMessageTextLen+1)); !errors.Is(err, ErrMessageTooLong) {
+		t.Fatalf("expected ErrMessageTooLong, got %v", err)
+	}
+	if err := validateMessageText("ok"); err != nil {
+		t.Fatalf("expected nil error, got %v", err)
+	}
+}
+
+func TestValidateCaptionText(t *testing.T) {
+	if err := validateCaptionText(strings.Repeat("a", maxMessageCaptionLen+1)); !errors.Is(err, ErrCaptionTooLong) {
+		t.Fatalf("expected ErrCaptionTooLong, got %v", err)
+	}
+	if err := validateCaptionText(""); err != nil {
+		t.Fatalf("expected nil error, got %v", err)
+	}
+}
+
+func TestSplitMessageTextPreservesContent(t *testing.T) {
+	text := "alpha beta\n" + strings.Repeat("x", maxMessageTextLen) + " omega"
+
+	parts := SplitMessageText(text)
+	if len(parts) < 2 {
+		t.Fatalf("expected multiple parts, got %d", len(parts))
+	}
+
+	for i, part := range parts {
+		if got := len([]rune(part)); got > maxMessageTextLen {
+			t.Fatalf("part %d exceeded limit: %d", i, got)
+		}
+	}
+
+	if got := strings.Join(parts, ""); got != text {
+		t.Fatalf("split/join mismatch: got %q want %q", got, text)
+	}
+}
+
+func TestAnswerLongSplitsRequestsAndAttachesKeyboardToLastChunk(t *testing.T) {
+	var requests []map[string]any
+
+	client := &http.Client{
+		Transport: roundTripFunc(func(req *http.Request) (*http.Response, error) {
+			body, err := io.ReadAll(req.Body)
+			if err != nil {
+				t.Fatalf("failed to read request body: %v", err)
+			}
+			var got map[string]any
+			if err := json.Unmarshal(body, &got); err != nil {
+				t.Fatalf("failed to decode request body: %v", err)
+			}
+			requests = append(requests, got)
+			return &http.Response{
+				StatusCode: http.StatusOK,
+				Header:     http.Header{"Content-Type": []string{"application/json"}},
+				Body:       io.NopCloser(strings.NewReader(`{"ok":true,"result":{"message_id":9,"date":1}}`)),
+			}, nil
+		}),
+	}
+
+	api := tgapi.NewAPI(
+		tgapi.NewAPIOpts("token").
+			SetAPIURL("https://example.test").
+			SetHTTPClient(client),
+	)
+	defer func() {
+		if err := api.Close(); err != nil {
+			t.Fatalf("Close returned error: %v", err)
+		}
+	}()
+
+	ctx := &MessageContext{
+		API:    api,
+		Msg:    &tgapi.Message{Chat: &tgapi.Chat{ID: 42, Type: tgapi.ChatTypePrivate}},
+		Logger: sneklog.NewLogger(),
+	}
+	kb := NewInlineKeyboardJSON(1).AddCallbackButton("A", "cmd")
+	text := strings.Repeat("a", maxMessageTextLen) + " " + strings.Repeat("b", 32)
+
+	messages := ctx.KeyboardLong(text, kb)
+	if got := len(messages); got != 2 {
+		t.Fatalf("expected 2 sent messages, got %d", got)
+	}
+	if got := len(requests); got != 2 {
+		t.Fatalf("expected 2 requests, got %d", got)
+	}
+	if _, ok := requests[0]["reply_markup"]; ok {
+		t.Fatal("did not expect keyboard on first chunk")
+	}
+	if _, ok := requests[1]["reply_markup"]; !ok {
+		t.Fatal("expected keyboard on final chunk")
+	}
+
+	gotTexts := []string{requests[0]["text"].(string), requests[1]["text"].(string)}
+	wantTexts := SplitMessageText(text)
+	if !reflect.DeepEqual(gotTexts, wantTexts) {
+		t.Fatalf("unexpected chunk texts: got %q want %q", gotTexts, wantTexts)
+	}
+}

msg_handler.go

@@ -0,0 +1,298 @@
+package laniakea
+
+import (
+	"strings"
+	"time"
+
+	"git.scuroneko.dev/scuroneko/laniakea/tgapi"
+)
+
+func (bot *Bot[T]) handleMessage(update *tgapi.Update, ctx *MessageContext) bool {
+	text, ok := messageText(update)
+	if !ok {
+		return false
+	}
+
+	prefix, cmd, args := bot.parseCommand(text)
+	if cmd == "" {
+		return bot.handleFallback(update, ctx)
+	}
+	ctx.Prefix = prefix
+
+	if strings.Contains(cmd, "@") {
+		botUsername := bot.username
+		if botUsername != "" && strings.HasSuffix(cmd, "@"+botUsername) {
+			cmd = cmd[:len(cmd)-len("@"+botUsername)] // remove @botname
+		}
+	}
+
+	for _, plugin := range bot.plugins {
+		if _, exists := plugin.commands[cmd]; exists {
+
+			ctx.Text = args
+			ctx.Args = strings.Fields(args)
+			ctx.Logger = plugin.logger
+
+			if ctx.Logger == nil {
+				ctx.Logger = bot.logger
+			}
+			if !plugin.executeMiddlewares(ctx, bot.appData) {
+				return false
+			}
+
+			startTime := time.Now()
+			bot.safeEmitEvent(ctx.Context(), HandlerStartedEvent{
+				UpdateID:    update.UpdateID,
+				UpdateType:  update.Type,
+				Plugin:      plugin.name,
+				HandlerKind: HandlerCommandKind,
+				HandlerName: cmd,
+				FromID:      ctx.FromID,
+				ChatID:      ctx.ChatID,
+			})
+
+			err := plugin.executeCmd(cmd, ctx, bot.appData)
+			handlerEndEvent := HandlerFinishedEvent{
+				UpdateID:    update.UpdateID,
+				UpdateType:  update.Type,
+				Plugin:      plugin.name,
+				HandlerKind: HandlerCommandKind,
+				HandlerName: cmd,
+				FromID:      ctx.FromID,
+				ChatID:      ctx.ChatID,
+				Duration:    time.Since(startTime),
+			}
+
+			var errorEvent *ErrorEvent = nil
+			if err != nil {
+				ctx.error(err)
+				handlerEndEvent.Err = err
+				handlerEndEvent.UserFacing = IsUserError(err)
+				errorEvent = &ErrorEvent{
+					UpdateID:    update.UpdateID,
+					UpdateType:  update.Type,
+					Plugin:      plugin.name,
+					HandlerKind: HandlerCommandKind,
+					HandlerName: cmd,
+					FromID:      ctx.FromID,
+					ChatID:      ctx.ChatID,
+					Err:         err,
+					UserFacing:  handlerEndEvent.UserFacing,
+				}
+			}
+			bot.safeEmitEvent(ctx.Context(), handlerEndEvent)
+			if errorEvent != nil {
+				bot.safeEmitEvent(ctx.Context(), *errorEvent)
+			}
+			return true
+		}
+	}
+
+	return bot.handleFallback(update, ctx)
+}
+
+func (bot *Bot[T]) handleFallback(update *tgapi.Update, ctx *MessageContext) bool {
+	text, ok := messageText(update)
+	if !ok {
+		return false
+	}
+
+	prefix, _, _ := bot.parseCommand(text)
+	handled := false
+	for _, plugin := range bot.plugins {
+		if plugin.messageFallback == nil {
+			continue
+		}
+
+		pluginCtx := cloneMsgContext(ctx)
+		pluginCtx.Prefix = prefix
+		pluginCtx.Text = text
+		pluginCtx.Args = strings.Fields(text)
+		if plugin.logger != nil {
+			pluginCtx.Logger = plugin.logger
+		}
+		if !plugin.executeMiddlewares(pluginCtx, bot.appData) {
+			continue
+		}
+
+		startTime := time.Now()
+		bot.safeEmitEvent(pluginCtx.Context(), HandlerStartedEvent{
+			UpdateID:    update.UpdateID,
+			UpdateType:  update.Type,
+			Plugin:      plugin.name,
+			HandlerKind: HandlerMessageKind,
+			HandlerName: "message_fallback",
+			FromID:      pluginCtx.FromID,
+			ChatID:      pluginCtx.ChatID,
+		})
+		err := plugin.messageFallback(pluginCtx, bot.appData)
+		endEvent := HandlerFinishedEvent{
+			UpdateID:    update.UpdateID,
+			UpdateType:  update.Type,
+			Plugin:      plugin.name,
+			HandlerKind: HandlerMessageKind,
+			HandlerName: "message_fallback",
+			FromID:      pluginCtx.FromID,
+			ChatID:      pluginCtx.ChatID,
+			Duration:    time.Since(startTime),
+		}
+		if err != nil {
+			endEvent.Err = err
+			endEvent.UserFacing = IsUserError(err)
+		}
+		bot.safeEmitEvent(pluginCtx.Context(), endEvent)
+		if err != nil {
+			pluginCtx.error(err)
+			bot.safeEmitEvent(pluginCtx.Context(), ErrorEvent{
+				UpdateID:    update.UpdateID,
+				UpdateType:  update.Type,
+				Plugin:      plugin.name,
+				HandlerKind: HandlerMessageKind,
+				HandlerName: "message_fallback",
+				FromID:      pluginCtx.FromID,
+				ChatID:      pluginCtx.ChatID,
+				Err:         err,
+				UserFacing:  IsUserError(err),
+			})
+		}
+		handled = true
+	}
+	return handled
+}
+
+func messageText(update *tgapi.Update) (string, bool) {
+	var msg *tgapi.Message
+	if update.Message != nil {
+		msg = update.Message
+	} else if update.ChannelPost != nil {
+		msg = update.ChannelPost
+	} else {
+		return "", false
+	}
+
+	var text string
+	if len(msg.Text) > 0 {
+		text = msg.Text
+	} else if len(msg.Caption) > 0 {
+		text = msg.Caption
+	} else {
+		return "", false
+	}
+	return text, true
+}
+
+func (bot *Bot[T]) handleCallback(update *tgapi.Update, ctx *MessageContext) bool {
+	data, err := bot.decodePayload(update.CallbackQuery.Data)
+	if err != nil {
+		bot.logger.Errorln(err)
+		bot.safeEmitEvent(ctx.Context(), ErrorEvent{
+			UpdateID:    update.UpdateID,
+			UpdateType:  update.Type,
+			Plugin:      "bot",
+			HandlerKind: HandlerPayloadKind,
+			HandlerName: "decodePayload",
+			FromID:      ctx.FromID,
+			ChatID:      ctx.ChatID,
+			Err:         err,
+			UserFacing:  false,
+		})
+		return false
+	}
+
+	ctx.Args = data.Args
+
+	for _, plugin := range bot.plugins {
+		_, ok := plugin.payloads[data.Command]
+		if !ok {
+			continue
+		}
+
+		ctx.Logger = plugin.logger
+		if ctx.Logger == nil {
+			ctx.Logger = bot.logger
+		}
+
+		if !plugin.executeMiddlewares(ctx, bot.appData) {
+			return false
+		}
+
+		startTime := time.Now()
+		bot.safeEmitEvent(ctx.Context(), HandlerStartedEvent{
+			UpdateID:    update.UpdateID,
+			UpdateType:  update.Type,
+			Plugin:      plugin.name,
+			HandlerKind: HandlerPayloadKind,
+			HandlerName: data.Command,
+			FromID:      ctx.FromID,
+			ChatID:      ctx.ChatID,
+		})
+		err := plugin.executePayload(data.Command, ctx, bot.appData)
+
+		endEvent := HandlerFinishedEvent{
+			UpdateID:    update.UpdateID,
+			UpdateType:  update.Type,
+			Plugin:      plugin.name,
+			HandlerKind: HandlerPayloadKind,
+			HandlerName: data.Command,
+			FromID:      ctx.FromID,
+			ChatID:      ctx.ChatID,
+			Duration:    time.Since(startTime),
+		}
+		var errorEvent *ErrorEvent = nil
+		if err != nil {
+			ctx.error(err)
+			errorEvent = &ErrorEvent{
+				UpdateID:    update.UpdateID,
+				UpdateType:  update.Type,
+				Plugin:      plugin.name,
+				HandlerKind: HandlerPayloadKind,
+				HandlerName: data.Command,
+				FromID:      ctx.FromID,
+				ChatID:      ctx.ChatID,
+				Err:         err,
+				UserFacing:  IsUserError(err),
+			}
+			endEvent.Err = err
+			endEvent.UserFacing = errorEvent.UserFacing
+		}
+		bot.safeEmitEvent(ctx.Context(), endEvent)
+		if errorEvent != nil {
+			bot.safeEmitEvent(ctx.Context(), *errorEvent)
+		}
+		return true
+	}
+	return false
+}
+
+func (bot *Bot[T]) checkPrefixes(text string) (string, bool) {
+	for _, prefix := range bot.prefixes {
+		if prefix == "" {
+			if bot.logger != nil {
+				bot.logger.Warnln("empty prefix is not allowed")
+			}
+			continue
+		}
+		if strings.HasPrefix(text, prefix) {
+			return prefix, true
+		}
+	}
+	return "", false
+}
+
+func (bot *Bot[T]) parseCommand(text string) (prefix, cmd, args string) {
+	if prefix, hasPrefix := bot.checkPrefixes(text); hasPrefix {
+		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:])
+		}
+		return prefix, cmd, args
+	}
+	return "", "", ""
+}

observer.go

@@ -0,0 +1,188 @@
+package laniakea
+
+import (
+	"context"
+	"fmt"
+	"time"
+
+	"git.scuroneko.dev/scuroneko/laniakea/tgapi"
+)
+
+// HandlerEventKind identifies the kind of handler observed by runtime events.
+type HandlerEventKind string
+
+const (
+	// HandlerCommandKind identifies a command handler.
+	HandlerCommandKind HandlerEventKind = "command"
+	// HandlerMessageKind identifies a message fallback handler.
+	HandlerMessageKind HandlerEventKind = "message"
+	// HandlerPayloadKind identifies a callback payload handler.
+	HandlerPayloadKind HandlerEventKind = "payload"
+	// HandlerUpdateKind identifies a generic update handler.
+	HandlerUpdateKind HandlerEventKind = "update"
+	// HandlerRunnerKind identifies a background runner execution.
+	HandlerRunnerKind HandlerEventKind = "runner"
+	// HandlerPollingKind identifies polling and getUpdates runtime work.
+	HandlerPollingKind HandlerEventKind = "polling"
+	// HandlerSceneKind identifies a scene runtime handler wrapper.
+	HandlerSceneKind HandlerEventKind = "scene"
+	// HandlerSceneStepKind identifies a scene step handler.
+	HandlerSceneStepKind HandlerEventKind = "scene_step"
+	// HandlerSceneCommandKind identifies a scene-local command handler.
+	HandlerSceneCommandKind HandlerEventKind = "scene_command"
+	// HandlerScenePayloadKind identifies a scene-local callback payload handler.
+	HandlerScenePayloadKind HandlerEventKind = "scene_payload"
+	// HandlerSceneMessageKind identifies a scene message fallback handler.
+	HandlerSceneMessageKind HandlerEventKind = "scene_message"
+)
+
+// Event is the marker interface implemented by all observer runtime events.
+type Event interface {
+	isEvent()
+}
+
+// UpdateReceivedEvent describes an update entering the bot runtime.
+type UpdateReceivedEvent struct {
+	UpdateID   int
+	UpdateType tgapi.UpdateType
+	FromID     int64
+	ChatID     int64
+}
+
+// UpdateHandledEvent describes a completed update execution path.
+type UpdateHandledEvent struct {
+	UpdateID   int
+	UpdateType tgapi.UpdateType
+	FromID     int64
+	ChatID     int64
+	Duration   time.Duration
+	Handled    bool
+}
+
+// HandlerStartedEvent describes a handler about to execute.
+type HandlerStartedEvent struct {
+	UpdateID    int
+	UpdateType  tgapi.UpdateType
+	Plugin      string
+	HandlerKind HandlerEventKind
+	HandlerName string
+	FromID      int64
+	ChatID      int64
+}
+
+// HandlerFinishedEvent describes a handler that has completed.
+type HandlerFinishedEvent struct {
+	UpdateID    int
+	UpdateType  tgapi.UpdateType
+	Plugin      string
+	HandlerKind HandlerEventKind
+	HandlerName string
+	FromID      int64
+	ChatID      int64
+	Duration    time.Duration
+	Err         error
+	UserFacing  bool
+}
+
+// SceneTransitionEvent describes a scene state transition.
+type SceneTransitionEvent struct {
+	Plugin string
+	Scene  string
+	From   string
+	To     string
+	Action SceneAction
+	FromID int64
+	ChatID int64
+}
+
+// PolicyCheckedEvent describes the result of a policy evaluation.
+type PolicyCheckedEvent struct {
+	Name     string
+	Plugin   string
+	FromID   int64
+	ChatID   int64
+	Passed   bool
+	Err      error
+	Internal bool
+}
+
+// RunnerFinishedEvent describes a completed background runner execution.
+type RunnerFinishedEvent struct {
+	Name     string
+	Duration time.Duration
+	Err      error
+}
+
+// PollingRetryEvent describes a polling retry after a failed getUpdates call.
+type PollingRetryEvent struct {
+	Attempt int
+	Delay   time.Duration
+	Err     error
+}
+
+// ErrorEvent describes an error routed through framework error handling.
+type ErrorEvent struct {
+	UpdateID    int
+	UpdateType  tgapi.UpdateType
+	Plugin      string
+	HandlerKind HandlerEventKind
+	HandlerName string
+	FromID      int64
+	ChatID      int64
+	Err         error
+	UserFacing  bool
+}
+
+func (UpdateReceivedEvent) isEvent()  {}
+func (UpdateHandledEvent) isEvent()   {}
+func (HandlerStartedEvent) isEvent()  {}
+func (HandlerFinishedEvent) isEvent() {}
+func (SceneTransitionEvent) isEvent() {}
+func (PolicyCheckedEvent) isEvent()   {}
+func (RunnerFinishedEvent) isEvent()  {}
+func (PollingRetryEvent) isEvent()    {}
+func (ErrorEvent) isEvent()           {}
+
+// Observer receives best-effort runtime instrumentation events.
+type Observer interface {
+	OnUpdateReceived(ctx context.Context, event UpdateReceivedEvent)
+	OnUpdateHandled(ctx context.Context, event UpdateHandledEvent)
+	OnHandlerStarted(ctx context.Context, event HandlerStartedEvent)
+	OnHandlerFinished(ctx context.Context, event HandlerFinishedEvent)
+	OnSceneTransition(ctx context.Context, event SceneTransitionEvent)
+	OnPolicyChecked(ctx context.Context, event PolicyCheckedEvent)
+	OnRunnerFinished(ctx context.Context, event RunnerFinishedEvent)
+	OnPollingRetry(ctx context.Context, event PollingRetryEvent)
+	OnError(ctx context.Context, event ErrorEvent)
+}
+
+func (bot *Bot[T]) safeEmitEvent(ctx context.Context, event Event) {
+	if bot.observer == nil {
+		return
+	}
+	defer func() {
+		if r := recover(); r != nil {
+			bot.logger.Errorln(fmt.Sprintf("panic in observer: %v", r))
+		}
+	}()
+	switch e := event.(type) {
+	case UpdateReceivedEvent:
+		bot.observer.OnUpdateReceived(ctx, e)
+	case UpdateHandledEvent:
+		bot.observer.OnUpdateHandled(ctx, e)
+	case HandlerStartedEvent:
+		bot.observer.OnHandlerStarted(ctx, e)
+	case HandlerFinishedEvent:
+		bot.observer.OnHandlerFinished(ctx, e)
+	case SceneTransitionEvent:
+		bot.observer.OnSceneTransition(ctx, e)
+	case PolicyCheckedEvent:
+		bot.observer.OnPolicyChecked(ctx, e)
+	case RunnerFinishedEvent:
+		bot.observer.OnRunnerFinished(ctx, e)
+	case PollingRetryEvent:
+		bot.observer.OnPollingRetry(ctx, e)
+	case ErrorEvent:
+		bot.observer.OnError(ctx, e)
+	}
+}

plugins.go

@@ -2,180 +2,43 @@ package laniakea
 
 import (
 	"errors"
-	"regexp"
 
-	"git.nix13.pw/scuroneko/extypes"
+	"git.scuroneko.dev/scuroneko/extypes"
-	"git.nix13.pw/scuroneko/laniakea/tgapi"
+	"git.scuroneko.dev/scuroneko/laniakea/tgapi"
-	"git.nix13.pw/scuroneko/laniakea/utils"
+	"git.scuroneko.dev/scuroneko/laniakea/utils"
-	"git.nix13.pw/scuroneko/slog"
+	"git.scuroneko.dev/scuroneko/sneklog/v2"
 )
 
-// CommandValueType defines the expected type of command argument.
-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"
-)
-
-var (
-	// CommandRegexInt matches one or more digits.
-	CommandRegexInt = regexp.MustCompile(`^\d+$`)
-	// CommandRegexString matches any non-empty string.
-	CommandRegexString = regexp.MustCompile(`^.+$`)
-	// CommandRegexBool matches true or false.
-	CommandRegexBool = regexp.MustCompile(`^(true|false)$`)
-)
-
-// 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 // Type of expected value
-	text      string           // Human-readable description (not used in validation)
-	regex     *regexp.Regexp   // Regex used to validate input
-	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) CommandArg {
-	return CommandArg{CommandValueAnyType, text, CommandRegexString, false}
-}
-
-// SetValueType sets expected value type and switches built-in validation regexp.
-func (c CommandArg) SetValueType(t CommandValueType) CommandArg {
-	regex := CommandRegexString
-	switch t {
-	case CommandValueIntType:
-		regex = CommandRegexInt
-	case CommandValueBoolType:
-		regex = CommandRegexBool
-	case CommandValueAnyType:
-		regex = nil // Skip validation
-	}
-	c.valueType = t
-	c.regex = regex
-	return c
-}
-
-// 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                       // The command trigger (e.g., "/start")
-	description string                       // Human-readable description for help
-	exec        CommandExecutor[T]           // Function to execute when command is triggered
-	args        extypes.Slice[CommandArg]    // List of expected arguments
-	middlewares extypes.Slice[Middleware[T]] // Optional middleware chain
-	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}
-}
-
-// NewPayload creates a new Command with the given executor, command payload string, and arguments.
-// The command string can contain any symbols, but it is recommended to use only "_", "-", ".", a-z, A-Z, and 0-9.
-func NewPayload[T any](exec CommandExecutor[T], command string, args ...CommandArg) *Command[T] {
-	return &Command[T]{command, "", exec, 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
-}
-
-// Internal helper that validates provided command arguments.
-func (c *Command[T]) validateArgs(args []string) error {
-	for i := range c.args.Len() {
-		if i >= len(args) && c.args.Get(i).required {
-			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 // Skip validation for CommandValueAnyType
-		}
-		if !cmdArg.regex.MatchString(arg) {
-			return ErrCmdArgRegexpMismatch
-		}
-	}
-	return nil
-}
-
 // Plugin represents a collection of commands and payloads (e.g., callback handlers),
 // with shared middleware and configuration.
 //
 // A Plugin is intended to be fully configured before it is passed to Bot.AddPlugins.
 // After registration, treat the plugin as committed and do not mutate it further.
 // Post-registration changes through the original *Plugin are not a supported API.
-type Plugin[T DbContext] struct {
+type Plugin[T AppData] struct {
 	name        string                       // Name of the plugin (e.g., "admin", "user")
 	commands    map[string]*Command[T]       // Registered commands (triggered by message)
 	payloads    map[string]*Command[T]       // Registered payloads (triggered by callback data)
+	scenes      map[string]*Scene[T]         // Optional scenes for multi-step interactions
 	middlewares extypes.Slice[Middleware[T]] // Shared middlewares for all commands/payloads
 	skipAutoCmd bool                         // If true, all commands in this plugin are excluded from auto-help
-	logger      *slog.Logger
+	logger      *sneklog.Logger
+	loggerOwned bool // true when the logger was created by the bot during registration; only owned loggers are closed by Close
 
-	handlers map[tgapi.UpdateType]CommandExecutor[T]
+	messageFallback CommandExecutor[T]
+	handlers        map[tgapi.UpdateType]CommandExecutor[T]
 
 	onClose func() error
 }
 
 // NewPlugin creates a new Plugin with the given name.
-func NewPlugin[T DbContext](name string) *Plugin[T] {
+func NewPlugin[T AppData](name string) *Plugin[T] {
 	return &Plugin[T]{
 		name:        name,
 		commands:    make(map[string]*Command[T]),
 		payloads:    make(map[string]*Command[T]),
 		middlewares: make(extypes.Slice[Middleware[T]], 0),
+		scenes:      make(map[string]*Scene[T]),
 		skipAutoCmd: false,
 		logger:      nil,
 		handlers:    make(map[tgapi.UpdateType]CommandExecutor[T]),
@@ -183,16 +46,24 @@ func NewPlugin[T DbContext](name string) *Plugin[T] {
 }
 
 // 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] {
+	if command == nil {
+		if p.logger != nil {
+			p.logger.Warnln("trying to add nil command")
+		}
+		return p
+	}
+	if _, exists := p.commands[command.command]; exists && p.logger != nil {
+		p.logger.Warnf("command '%s' already registered in plugin '%s'; overwriting", command.command, p.name)
+	}
 	p.commands[command.command] = command
 	return p
 }
 
-// NewCommand creates and immediately adds a new command to the plugin.
+// Command 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] {
+func (p *Plugin[T]) Command(command string, exec CommandExecutor[T], args ...CommandArg) *Command[T] {
-	cmd := NewCommand(exec, command, args...)
+	cmd := NewCommand(command, exec, args...)
 	p.AddCommand(cmd)
 	return cmd
 }
@@ -200,30 +71,96 @@ func (p *Plugin[T]) NewCommand(exec CommandExecutor[T], command string, args ...
 // 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] {
+	if command == nil {
+		if p.logger != nil {
+			p.logger.Warnln("trying to add nil command")
+		}
+		return p
+	}
+	if _, exists := p.payloads[command.command]; exists && p.logger != nil {
+		p.logger.Warnf("payload '%s' is already registered in plugin '%s'; overwriting", command.command, p.name)
+	}
 	p.payloads[command.command] = command
 	return p
 }
 
-// NewPayload creates and immediately adds a new payload command to the plugin.
+// Payload creates and immediately adds a new payload command to the plugin.
 // Returns the created payload command for further configuration.
-func (p *Plugin[T]) NewPayload(exec CommandExecutor[T], command string, args ...CommandArg) *Command[T] {
+func (p *Plugin[T]) Payload(command string, exec CommandExecutor[T], args ...CommandArg) *Command[T] {
-	cmd := NewPayload(exec, command, args...)
+	cmd := NewCommand(command, exec, args...)
 	p.AddPayload(cmd)
 	return cmd
 }
 
+// Scene creates, registers, and returns a new scene owned by the plugin.
+func (p *Plugin[T]) Scene(name string) *Scene[T] {
+	scene := NewScene[T](name)
+	scene.setPluginName(p.name)
+	p.AddScene(scene)
+	return scene
+}
+
+// AddScene registers a multi-step scene in the plugin.
+func (p *Plugin[T]) AddScene(scene *Scene[T]) *Plugin[T] {
+	if scene == nil {
+		return p
+	}
+	scene.pluginName = p.name
+	if _, exists := p.scenes[scene.name]; exists && p.logger != nil {
+		p.logger.Warnf("scene '%s' already registered in plugin '%s'; overwriting", scene.name, p.name)
+	}
+	p.scenes[scene.name] = scene
+	return p
+}
+
+// CommandGroup configures and registers a prefixed command group.
+func (p *Plugin[T]) CommandGroup(prefix string, groupFunc func(group *CommandGroup[T])) *Plugin[T] {
+	if groupFunc == nil {
+		return p
+	}
+	group := NewCommandGroup[T](prefix)
+	groupFunc(group)
+	if len(group.commands) == 0 {
+		return p
+	}
+	for _, cmd := range group.Build() {
+		p.AddCommand(cmd)
+	}
+	return p
+}
+
+// AddCommandGroup registers every command built by group.
+func (p *Plugin[T]) AddCommandGroup(group *CommandGroup[T]) *Plugin[T] {
+	if group == nil {
+		return p
+	}
+	if len(group.commands) == 0 {
+		return p
+	}
+	for _, cmd := range group.Build() {
+		p.AddCommand(cmd)
+	}
+	return p
+}
+
+// UsePolicy registers a Policy as plugin middleware for all plugin handlers.
+func (p *Plugin[T]) UsePolicy(name string, policy Policy[T]) *Plugin[T] {
+	mw := RequirePolicy(name, policy)
+	return p.AddMiddleware(mw)
+}
+
 // AddUpdateHandler registers a handler for a non-command update type.
 // Message, channel post, and callback query updates stay on the command/payload flow.
 func (p *Plugin[T]) AddUpdateHandler(t tgapi.UpdateType, handler CommandExecutor[T]) *Plugin[T] {
 	switch t {
 	case tgapi.UpdateTypeMessage, tgapi.UpdateTypeChannelPost, tgapi.UpdateTypeCallbackQuery:
 		if p.logger == nil {
-			logger := utils.CreateLogger(p.name, utils.GetLoggerLevel())
+			logger := utils.CreateLogger(p.name, utils.GetLoggerLevel(), utils.LogFormatText, nil)
-			logger.Warnf("%s can't be registred through AddUpdateHandler. Use AddPayload/NewPayload or AddCommand/NewCommand", t)
+			logger.Warnf("%s can't be registered through AddUpdateHandler. Use AddPayload/Payload or AddCommand/Command", t)
 			_ = logger.Close()
 			return p
 		}
-		p.logger.Warnf("%s can't be registred through AddUpdateHandler. Use AddPayload/NewPayload or AddCommand/NewCommand", t)
+		p.logger.Warnf("%s can't be registered through AddUpdateHandler. Use AddPayload/Payload or AddCommand/Command", t)
 		return p
 	}
 	p.handlers[t] = handler
@@ -247,7 +184,7 @@ func (p *Plugin[T]) SkipCommandAutoGen() *Plugin[T] {
 //
 // Call this before Bot.AddPlugins. If the plugin is already registered, changing
 // the original *Plugin does not update the Bot's internal copy.
-func (p *Plugin[T]) SetLogger(l *slog.Logger) *Plugin[T] {
+func (p *Plugin[T]) SetLogger(l *sneklog.Logger) *Plugin[T] {
 	p.logger = l
 	return p
 }
@@ -271,11 +208,22 @@ func (p *Plugin[T]) SetOnClose(f func() error) *Plugin[T] {
 	return p
 }
 
+// SetMessageFallback registers a fallback handler for messages that do not
+// match a command.
+func (p *Plugin[T]) SetMessageFallback(handler CommandExecutor[T]) *Plugin[T] {
+	p.messageFallback = handler
+	return p
+}
+
 // Close releases plugin-owned resources such as its logger and optional
 // OnClose callback.
+//
+// Only loggers created by the bot during registration are closed. A logger
+// supplied via SetLogger remains the caller's responsibility — the framework
+// never closes a logger it does not own.
 func (p *Plugin[T]) Close() error {
 	var e []error
-	if p.logger != nil {
+	if p.logger != nil && p.loggerOwned {
 		if err := p.logger.Close(); err != nil {
 			e = append(e, err)
 		}
@@ -288,56 +236,49 @@ func (p *Plugin[T]) Close() error {
 	return errors.Join(e...)
 }
 
-// Internal helper that validates and executes a command handler.
+func (p *Plugin[T]) executeCmd(cmd string, ctx *MessageContext, db T) error {
-func (p *Plugin[T]) executeCmd(cmd string, ctx *MsgContext, db T) {
 	command, exists := p.commands[cmd]
 	if !exists {
-		ctx.error(errors.New("command not found"))
+		return AsInternalError(errCommandNotFound)
-		return
 	}
 
 	if err := command.validateArgs(ctx.Args); err != nil {
-		ctx.error(err)
+		return AsUserError(err)
-		return
 	}
 
 	// Run command-specific middlewares
 	for _, m := range command.middlewares {
 		if !m.Execute(ctx, db) {
-			return
+			return AsInternalError(errors.New("middleware blocked call"))
 		}
 	}
 
 	// Execute command
-	command.exec(ctx, db)
+	return command.exec(ctx, db)
 }
 
-// Internal helper that validates and executes a payload handler.
+func (p *Plugin[T]) executePayload(payload string, ctx *MessageContext, db T) error {
-func (p *Plugin[T]) executePayload(payload string, ctx *MsgContext, db T) {
 	command, exists := p.payloads[payload]
 	if !exists {
-		ctx.error(errors.New("payload not found"))
+		return AsInternalError(errPayloadNotFound)
-		return
 	}
 
 	if err := command.validateArgs(ctx.Args); err != nil {
-		ctx.error(err)
+		return AsUserError(err)
-		return
 	}
 
 	// Run command-specific middlewares
 	for _, m := range command.middlewares {
 		if !m.Execute(ctx, db) {
-			return
+			return AsInternalError(errors.New("middleware blocked call"))
 		}
 	}
 
 	// Execute payload
-	command.exec(ctx, db)
+	return command.exec(ctx, db)
 }
 
-// Internal helper that runs plugin middlewares in order.
+func (p *Plugin[T]) executeMiddlewares(ctx *MessageContext, db T) bool {
-func (p *Plugin[T]) executeMiddlewares(ctx *MsgContext, db T) bool {
 	for _, m := range p.middlewares {
 		if !m.Execute(ctx, db) {
 			return false
@@ -349,19 +290,19 @@ func (p *Plugin[T]) executeMiddlewares(ctx *MsgContext, db T) bool {
 // 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
+type MiddlewareExecutor[T AppData] func(ctx *MessageContext, db T) bool
 
 // Middleware represents a reusable execution interceptor.
 // Can be synchronous (blocking) or asynchronous (non-blocking).
-type Middleware[T DbContext] struct {
+type Middleware[T AppData] struct {
 	name     string                // Human-readable name for logging/debugging
 	executor MiddlewareExecutor[T] // Function to execute
-	order    int                   // Optional sort order (not used yet)
+	order    int                   // Sort order for bot-level middleware ordering
 	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] {
+func NewMiddleware[T AppData](name string, executor MiddlewareExecutor[T]) Middleware[T] {
 	return Middleware[T]{name, executor, 0, false}
 }
 
@@ -381,12 +322,19 @@ func (m Middleware[T]) SetAsync(async bool) Middleware[T] {
 // 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 {
+//
+// Async note: the goroutine receives a shallow copy of MessageContext, so
+// scalar fields (FromID, ChatID, CallbackQueryID, ...) remain a stable
+// snapshot. Pointer and slice fields (Msg, From, Chat, API, Logger, Args)
+// continue to share storage with the synchronous flow. Async middleware
+// must treat those fields as read-only — mutating them races the sync chain
+// that mutates the same context concurrently.
+func (m Middleware[T]) Execute(ctx *MessageContext, db T) bool {
 	if m.async {
-		ctx := *ctx // copy context to avoid race condition
+		ctxCopy := *ctx
-		go func(ctx MsgContext) {
+		go func(ctx MessageContext) {
 			m.executor(&ctx, db)
-		}(ctx)
+		}(ctxCopy)
 		return true
 	}
 	return m.executor(ctx, db)

plugins_test.go

@@ -6,7 +6,7 @@ import (
 )
 
 func TestValidateArgsRequiresFullMatch(t *testing.T) {
-	intCmd := NewCommand[NoDB](func(ctx *MsgContext, db NoDB) {}, "int", NewCommandArg("n").SetValueType(CommandValueIntType).SetRequired())
+	intCmd := NewCommand("int", func(ctx *MessageContext, db NoData) error { return nil }, NewCommandArg("n").SetValueType(CommandValueInt).SetRequired())
 	if err := intCmd.validateArgs([]string{"123"}); err != nil {
 		t.Fatalf("expected valid integer argument, got %v", err)
 	}
@@ -14,7 +14,7 @@ func TestValidateArgsRequiresFullMatch(t *testing.T) {
 		t.Fatalf("expected ErrCmdArgRegexpMismatch for partial int match, got %v", err)
 	}
 
-	boolCmd := NewCommand[NoDB](func(ctx *MsgContext, db NoDB) {}, "bool", NewCommandArg("flag").SetValueType(CommandValueBoolType).SetRequired())
+	boolCmd := NewCommand("bool", func(ctx *MessageContext, db NoData) error { return nil }, NewCommandArg("flag").SetValueType(CommandValueBool).SetRequired())
 	if err := boolCmd.validateArgs([]string{"false"}); err != nil {
 		t.Fatalf("expected valid bool argument, got %v", err)
 	}
@@ -24,9 +24,9 @@ func TestValidateArgsRequiresFullMatch(t *testing.T) {
 }
 
 func TestValidateArgsEnforcesRequiredArgIndex(t *testing.T) {
-	cmd := NewCommand[NoDB](
+	cmd := NewCommand(
-		func(ctx *MsgContext, db NoDB) {},
 		"mixed",
+		func(ctx *MessageContext, db NoData) error { return nil },
 		NewCommandArg("optional"),
 		NewCommandArg("required").SetRequired(),
 	)
@@ -38,3 +38,81 @@ func TestValidateArgsEnforcesRequiredArgIndex(t *testing.T) {
 		t.Fatalf("expected both args to validate, got %v", err)
 	}
 }
+
+func TestCommandGroupBuildsPrefixedCommandsWithoutMutatingOriginal(t *testing.T) {
+	groupMiddleware := NewMiddleware("group", func(ctx *MessageContext, db NoData) bool { return true })
+	commandMiddleware := NewMiddleware("command", func(ctx *MessageContext, db NoData) bool { return true })
+	cmd := NewCommand("ban", func(ctx *MessageContext, db NoData) error { return nil }).
+		SetDescription("Ban user").
+		Use(commandMiddleware)
+
+	group := NewCommandGroup[NoData]("admin_").
+		Use(groupMiddleware).
+		AddCommand(cmd)
+
+	built := group.Build()
+	if len(built) != 1 {
+		t.Fatalf("expected one command, got %d", len(built))
+	}
+
+	grouped := built[0]
+	if grouped.command != "admin_ban" {
+		t.Fatalf("expected prefixed command name, got %q", grouped.command)
+	}
+	if grouped.description != "Ban user" {
+		t.Fatalf("expected description to be copied, got %q", grouped.description)
+	}
+	if cmd.command != "ban" {
+		t.Fatalf("expected original command name to stay unchanged, got %q", cmd.command)
+	}
+	if len(cmd.middlewares) != 1 || cmd.middlewares[0].name != "command" {
+		t.Fatalf("expected original command middleware to stay unchanged, got %#v", cmd.middlewares)
+	}
+	if len(grouped.middlewares) != 2 {
+		t.Fatalf("expected group and command middleware, got %d", len(grouped.middlewares))
+	}
+	if grouped.middlewares[0].name != "group" || grouped.middlewares[1].name != "command" {
+		t.Fatalf("expected group middleware before command middleware, got %q then %q", grouped.middlewares[0].name, grouped.middlewares[1].name)
+	}
+}
+
+func TestCommandGroupBuildIsRepeatable(t *testing.T) {
+	group := NewCommandGroup[NoData]("admin").
+		Use(NewMiddleware("group", func(ctx *MessageContext, db NoData) bool { return true })).
+		AddCommand(NewCommand("ban", func(ctx *MessageContext, db NoData) error { return nil }).
+			Use(NewMiddleware("command", func(ctx *MessageContext, db NoData) bool { return true })))
+
+	first := group.Build()
+	second := group.Build()
+
+	if len(first) != 1 || len(second) != 1 {
+		t.Fatalf("expected one command from each build, got %d and %d", len(first), len(second))
+	}
+	if len(first[0].middlewares) != 2 {
+		t.Fatalf("expected first build to have two middlewares, got %d", len(first[0].middlewares))
+	}
+	if len(second[0].middlewares) != 2 {
+		t.Fatalf("expected second build to have two middlewares, got %d", len(second[0].middlewares))
+	}
+	if first[0] == second[0] {
+		t.Fatal("expected repeated Build calls to return distinct command copies")
+	}
+}
+
+func TestPluginCommandGroupRegistersBuiltCommands(t *testing.T) {
+	plugin := NewPlugin[NoData]("admin")
+
+	plugin.CommandGroup("admin_", func(group *CommandGroup[NoData]) {
+		group.AddCommand(NewCommand("ban", func(ctx *MessageContext, db NoData) error { return nil }))
+	})
+
+	if _, ok := plugin.commands["admin_ban"]; !ok {
+		t.Fatal("expected plugin to register prefixed command")
+	}
+	if _, ok := plugin.commands["ban"]; ok {
+		t.Fatal("expected plugin not to register unprefixed command")
+	}
+
+	plugin.CommandGroup("ignored", nil)
+	plugin.AddCommandGroup(nil)
+}

policy.go

@@ -0,0 +1,221 @@
+package laniakea
+
+import (
+	"errors"
+	"fmt"
+
+	"git.scuroneko.dev/scuroneko/laniakea/tgapi"
+)
+
+// Policy defines a reusable authorization rule for the current update context.
+type Policy[T AppData] func(ctx *MessageContext, data T) error
+
+// RequirePolicy adapts a Policy into a blocking middleware.
+func RequirePolicy[T AppData](name string, p Policy[T]) Middleware[T] {
+	return NewMiddleware(name, func(ctx *MessageContext, data T) bool {
+		if err := p(ctx, data); err != nil {
+			ctx.emitPolicyChecked(PolicyCheckedEvent{
+				Name:     name,
+				FromID:   ctx.FromID,
+				ChatID:   ctx.ChatID,
+				Passed:   false,
+				Err:      err,
+				Internal: IsInternalError(err),
+			})
+			ctx.error(err)
+			return false
+		}
+		ctx.emitPolicyChecked(PolicyCheckedEvent{
+			Name:   name,
+			FromID: ctx.FromID,
+			ChatID: ctx.ChatID,
+			Passed: true,
+		})
+		return true
+	})
+}
+
+// AllPolicies composes policies that all must succeed.
+func AllPolicies[T AppData](policies ...Policy[T]) Policy[T] {
+	return func(ctx *MessageContext, data T) error {
+		for _, p := range policies {
+			if err := p(ctx, data); err != nil {
+				return err
+			}
+		}
+		return nil
+	}
+}
+
+// AnyPolicy composes policies where at least one must succeed.
+func AnyPolicy[T AppData](policies ...Policy[T]) Policy[T] {
+	return func(ctx *MessageContext, data T) error {
+		var firstDeny error
+		var internalErr error
+		for _, p := range policies {
+			err := p(ctx, data)
+			if err == nil {
+				return nil
+			}
+			if IsInternalError(err) {
+				if internalErr == nil {
+					internalErr = err
+				}
+				continue
+			}
+			if firstDeny == nil {
+				firstDeny = err
+			}
+		}
+		if internalErr != nil {
+			return internalErr
+		}
+		if firstDeny != nil {
+			return firstDeny
+		}
+		return AsUserError(errors.New("no policy matched"))
+	}
+}
+
+// NotPolicy inverts a policy deny result while preserving internal failures.
+func NotPolicy[T AppData](policy Policy[T]) Policy[T] {
+	return func(ctx *MessageContext, data T) error {
+		var err error
+		if err = policy(ctx, data); err == nil {
+			return AsUserError(errors.New("the action is not allowed due to policy violation"))
+		}
+		if IsInternalError(err) {
+			return err
+		}
+		return nil
+	}
+}
+
+// RequirePrivateChat allows execution only in private chats.
+func RequirePrivateChat[T AppData]() Policy[T] {
+	return func(ctx *MessageContext, data T) error {
+		if ctx.Msg == nil || ctx.Msg.Chat == nil {
+			return AsInternalError(errors.New("private-chat policy requires message chat context"))
+		}
+
+		if ctx.Msg.Chat.Type != tgapi.ChatTypePrivate {
+			return AsUserError(errors.New("this action is only available in private chat"))
+		}
+
+		return nil
+	}
+}
+
+// RequireGroupChat allows execution only in group or supergroup chats.
+func RequireGroupChat[T AppData]() Policy[T] {
+	return func(ctx *MessageContext, data T) error {
+		if ctx.Msg == nil || ctx.Msg.Chat == nil {
+			return AsInternalError(errors.New("group-chat policy requires message chat context"))
+		}
+
+		if ctx.Msg.Chat.Type != tgapi.ChatTypeGroup && ctx.Msg.Chat.Type != tgapi.ChatTypeSupergroup {
+			return AsUserError(errors.New("this action is only available in group chats"))
+		}
+
+		return nil
+	}
+}
+
+// RequireSupergroupChat allows execution only in supergroup chats.
+func RequireSupergroupChat[T AppData]() Policy[T] {
+	return func(ctx *MessageContext, data T) error {
+		if ctx.Msg == nil || ctx.Msg.Chat == nil {
+			return AsInternalError(errors.New("supergroup-chat policy requires message chat context"))
+		}
+
+		if ctx.Msg.Chat.Type != tgapi.ChatTypeSupergroup {
+			return AsUserError(errors.New("this action is only available in supergroup chats"))
+		}
+
+		return nil
+	}
+}
+
+// RequireChatAdmin allows execution only for chat administrators or owners.
+func RequireChatAdmin[T AppData]() Policy[T] {
+	return func(ctx *MessageContext, data T) error {
+		if ctx.FromID == 0 || ctx.ChatID == 0 {
+			return AsInternalError(errors.New("chat-admin policy requires message chat context"))
+		}
+
+		member, err := ctx.API.GetChatMember(tgapi.GetChatMember{
+			ChatID: ctx.ChatID,
+			UserID: ctx.FromID,
+		})
+		if err != nil {
+			return AsInternalError(fmt.Errorf("failed to fetch chat member status: %w", err))
+		}
+
+		if member.Status != tgapi.ChatMemberStatusAdministrator && member.Status != tgapi.ChatMemberStatusOwner {
+			return AsUserError(errors.New("this action is only available to chat admins"))
+		}
+
+		return nil
+	}
+}
+
+// RequireChatCreator allows execution only for the chat owner.
+func RequireChatCreator[T AppData]() Policy[T] {
+	return func(ctx *MessageContext, data T) error {
+		if ctx.FromID == 0 || ctx.ChatID == 0 {
+			return AsInternalError(errors.New("chat-creator policy requires message chat context"))
+		}
+
+		member, err := ctx.API.GetChatMember(tgapi.GetChatMember{
+			ChatID: ctx.ChatID,
+			UserID: ctx.FromID,
+		})
+		if err != nil {
+			return AsInternalError(fmt.Errorf("failed to fetch chat creator: %w", err))
+		}
+
+		if member.Status != tgapi.ChatMemberStatusOwner {
+			return AsUserError(errors.New("this action is only available to the chat creator"))
+		}
+
+		return nil
+	}
+}
+
+// RequireBotAdmin allows execution only when the bot is an admin in the chat.
+func RequireBotAdmin[T AppData]() Policy[T] {
+	return func(ctx *MessageContext, data T) error {
+		if ctx.ChatID == 0 {
+			return AsInternalError(errors.New("bot-admin policy requires message chat context"))
+		}
+		if ctx.botID == 0 {
+			return AsInternalError(errors.New("bot ID is not set in context"))
+		}
+
+		member, err := ctx.API.GetChatMember(tgapi.GetChatMember{
+			ChatID: ctx.ChatID, UserID: ctx.botID,
+		})
+		if err != nil {
+			return AsInternalError(fmt.Errorf("failed to fetch bot member status: %w", err))
+		}
+
+		if member.Status != tgapi.ChatMemberStatusAdministrator && member.Status != tgapi.ChatMemberStatusOwner {
+			return AsUserError(errors.New("this action requires the bot to be an admin in the chat"))
+		}
+
+		return nil
+	}
+}
+
+// RequireCallbackFromUser allows execution only for callback queries sent by non-bot users.
+func RequireCallbackFromUser[T AppData]() Policy[T] {
+	return func(ctx *MessageContext, data T) error {
+		if ctx.Update.CallbackQuery == nil {
+			return AsInternalError(errors.New("callback-user policy requires callback query context"))
+		}
+		if ctx.Update.CallbackQuery.From.IsBot {
+			return AsUserError(errors.New("this action is only available to human users"))
+		}
+		return nil
+	}
+}

policy_test.go

@@ -0,0 +1,281 @@
+package laniakea
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"io"
+	"net/http"
+	"strings"
+	"testing"
+
+	"git.scuroneko.dev/scuroneko/laniakea/tgapi"
+	"git.scuroneko.dev/scuroneko/sneklog/v2"
+)
+
+func TestRequirePolicyStopsExecutionOnDeniedPolicy(t *testing.T) {
+	var requests int
+	var gotBody map[string]any
+
+	client := &http.Client{
+		Transport: roundTripFunc(func(req *http.Request) (*http.Response, error) {
+			requests++
+			body, err := io.ReadAll(req.Body)
+			if err != nil {
+				t.Fatalf("failed to read request body: %v", err)
+			}
+			if err := json.Unmarshal(body, &gotBody); err != nil {
+				t.Fatalf("failed to decode request body: %v", err)
+			}
+			return &http.Response{
+				StatusCode: http.StatusOK,
+				Header:     http.Header{"Content-Type": []string{"application/json"}},
+				Body:       io.NopCloser(strings.NewReader(`{"ok":true,"result":{"message_id":9,"date":1}}`)),
+			}, nil
+		}),
+	}
+
+	api := tgapi.NewAPI(
+		tgapi.NewAPIOpts("token").
+			SetAPIURL("https://example.test").
+			SetHTTPClient(client),
+	)
+	defer func() {
+		if err := api.Close(); err != nil {
+			t.Fatalf("Close returned error: %v", err)
+		}
+	}()
+
+	ctx := &MessageContext{
+		API:           api,
+		Msg:           &tgapi.Message{Chat: &tgapi.Chat{ID: 42, Type: tgapi.ChatTypePrivate}},
+		Logger:        sneklog.NewLogger(),
+		errorTemplate: "Error: %s",
+	}
+
+	mw := RequirePolicy("deny", func(ctx *MessageContext, data NoData) error {
+		return AsUserError(errors.New("blocked"))
+	})
+
+	if mw.Execute(ctx, NoData{}) {
+		t.Fatal("expected denied policy middleware to stop execution")
+	}
+	if requests != 1 {
+		t.Fatalf("expected one user-facing error reply, got %d requests", requests)
+	}
+	if got := gotBody["text"]; got != "Error: blocked" {
+		t.Fatalf("unexpected policy error reply text: %v", got)
+	}
+}
+
+func TestRequirePrivateChatAllowsPrivateChat(t *testing.T) {
+	ctx := &MessageContext{
+		Msg: &tgapi.Message{
+			Chat: &tgapi.Chat{ID: 42, Type: tgapi.ChatTypePrivate},
+		},
+		Logger: sneklog.NewLogger(),
+	}
+
+	if err := RequirePrivateChat[NoData]()(ctx, NoData{}); err != nil {
+		t.Fatalf("RequirePrivateChat returned error: %v", err)
+	}
+}
+
+func TestRequirePrivateChatDeniesNonPrivateChat(t *testing.T) {
+	ctx := &MessageContext{
+		Msg: &tgapi.Message{
+			Chat: &tgapi.Chat{ID: -100, Type: tgapi.ChatTypeSupergroup},
+		},
+		Logger: sneklog.NewLogger(),
+	}
+
+	err := RequirePrivateChat[NoData]()(ctx, NoData{})
+	if err == nil {
+		t.Fatal("expected RequirePrivateChat to deny non-private chats")
+	}
+	if !IsUserError(err) {
+		t.Fatalf("expected user-visible deny error, got %v", err)
+	}
+}
+
+func TestRequireChatAdminUsesNormalizedIDs(t *testing.T) {
+	var sawGetChatMember bool
+	var gotBody map[string]any
+
+	client := &http.Client{
+		Transport: roundTripFunc(func(req *http.Request) (*http.Response, error) {
+			if !strings.Contains(req.URL.Path, "getChatMember") {
+				t.Fatalf("unexpected API method: %s", req.URL.Path)
+			}
+			sawGetChatMember = true
+			body, err := io.ReadAll(req.Body)
+			if err != nil {
+				t.Fatalf("failed to read request body: %v", err)
+			}
+			if err := json.Unmarshal(body, &gotBody); err != nil {
+				t.Fatalf("failed to decode request body: %v", err)
+			}
+			return &http.Response{
+				StatusCode: http.StatusOK,
+				Header:     http.Header{"Content-Type": []string{"application/json"}},
+				Body: io.NopCloser(strings.NewReader(
+					`{"ok":true,"result":{"status":"administrator","user":{"id":55,"is_bot":false,"first_name":"tester"}}}`,
+				)),
+			}, nil
+		}),
+	}
+
+	api := tgapi.NewAPI(
+		tgapi.NewAPIOpts("token").
+			SetAPIURL("https://example.test").
+			SetHTTPClient(client),
+	)
+	defer func() {
+		if err := api.Close(); err != nil {
+			t.Fatalf("Close returned error: %v", err)
+		}
+	}()
+
+	ctx := &MessageContext{
+		API:    api,
+		ChatID: -2001,
+		FromID: 55,
+		Logger: sneklog.NewLogger(),
+	}
+
+	if err := RequireChatAdmin[NoData]()(ctx, NoData{}); err != nil {
+		t.Fatalf("RequireChatAdmin returned error: %v", err)
+	}
+	if !sawGetChatMember {
+		t.Fatal("expected GetChatMember to be called")
+	}
+	if got := gotBody["chat_id"]; got != float64(-2001) {
+		t.Fatalf("unexpected chat_id in request: %v", got)
+	}
+	if got := gotBody["user_id"]; got != float64(55) {
+		t.Fatalf("unexpected user_id in request: %v", got)
+	}
+}
+
+func TestAllPoliciesReturnsFirstError(t *testing.T) {
+	want := AsUserError(errors.New("blocked"))
+	policy := AllPolicies(
+		func(ctx *MessageContext, data NoData) error { return nil },
+		func(ctx *MessageContext, data NoData) error { return want },
+		func(ctx *MessageContext, data NoData) error {
+			t.Fatal("unexpected evaluation after first failure")
+			return nil
+		},
+	)
+
+	err := policy(&MessageContext{Logger: sneklog.NewLogger()}, NoData{})
+	if !errors.Is(err, want) {
+		t.Fatalf("expected first policy error, got %v", err)
+	}
+}
+
+func TestAnyPolicyAllowsLaterSuccessAfterInternalError(t *testing.T) {
+	policy := AnyPolicy(
+		func(ctx *MessageContext, data NoData) error { return AsInternalError(errors.New("temporary")) },
+		func(ctx *MessageContext, data NoData) error { return nil },
+	)
+
+	if err := policy(&MessageContext{Logger: sneklog.NewLogger()}, NoData{}); err != nil {
+		t.Fatalf("expected later success to allow access, got %v", err)
+	}
+}
+
+func TestAnyPolicyReturnsInternalErrorWhenNonePass(t *testing.T) {
+	internal := AsInternalError(errors.New("temporary"))
+	policy := AnyPolicy(
+		func(ctx *MessageContext, data NoData) error { return AsUserError(errors.New("denied")) },
+		func(ctx *MessageContext, data NoData) error { return internal },
+	)
+
+	err := policy(&MessageContext{Logger: sneklog.NewLogger()}, NoData{})
+	if !errors.Is(err, internal) {
+		t.Fatalf("expected internal error, got %v", err)
+	}
+}
+
+func TestAnyPolicyReturnsFirstDenyWhenNoPolicyPasses(t *testing.T) {
+	first := AsUserError(errors.New("first deny"))
+	policy := AnyPolicy(
+		func(ctx *MessageContext, data NoData) error { return first },
+		func(ctx *MessageContext, data NoData) error { return AsUserError(errors.New("second deny")) },
+	)
+
+	err := policy(&MessageContext{Logger: sneklog.NewLogger()}, NoData{})
+	if !errors.Is(err, first) {
+		t.Fatalf("expected first deny error, got %v", err)
+	}
+}
+
+func TestNotPolicyInvertsUserDenyButPreservesInternalErrors(t *testing.T) {
+	inverted := NotPolicy(func(ctx *MessageContext, data NoData) error {
+		return AsUserError(errors.New("denied"))
+	})
+	if err := inverted(&MessageContext{Logger: sneklog.NewLogger()}, NoData{}); err != nil {
+		t.Fatalf("expected inverted deny to succeed, got %v", err)
+	}
+
+	internal := AsInternalError(errors.New("temporary"))
+	preserve := NotPolicy(func(ctx *MessageContext, data NoData) error {
+		return internal
+	})
+	err := preserve(&MessageContext{Logger: sneklog.NewLogger()}, NoData{})
+	if !errors.Is(err, internal) {
+		t.Fatalf("expected internal error to be preserved, got %v", err)
+	}
+}
+
+func TestRequirePolicyEmitsObserverEvents(t *testing.T) {
+	t.Run("allow", func(t *testing.T) {
+		observer := &recordingObserver{}
+		ctx := &MessageContext{
+			Logger:   sneklog.NewLogger(),
+			ctx:      context.Background(),
+			observer: observer,
+			FromID:   10,
+			ChatID:   20,
+		}
+
+		mw := RequirePolicy("allow", func(ctx *MessageContext, data NoData) error {
+			return nil
+		})
+
+		if !mw.Execute(ctx, NoData{}) {
+			t.Fatal("expected allowed policy middleware to continue execution")
+		}
+		if len(observer.policies) != 1 {
+			t.Fatalf("expected one policy event, got %d", len(observer.policies))
+		}
+		if got := observer.policies[0]; got.Name != "allow" || !got.Passed || got.Err != nil || got.Internal {
+			t.Fatalf("unexpected policy event: %#v", got)
+		}
+	})
+
+	t.Run("deny", func(t *testing.T) {
+		observer := &recordingObserver{}
+		ctx := &MessageContext{
+			Logger:        sneklog.NewLogger(),
+			ctx:           context.Background(),
+			observer:      observer,
+			errorTemplate: "%s",
+		}
+
+		mw := RequirePolicy("deny", func(ctx *MessageContext, data NoData) error {
+			return AsInternalError(errors.New("blocked"))
+		})
+
+		if mw.Execute(ctx, NoData{}) {
+			t.Fatal("expected denied policy middleware to stop execution")
+		}
+		if len(observer.policies) != 1 {
+			t.Fatalf("expected one policy event, got %d", len(observer.policies))
+		}
+		if got := observer.policies[0]; got.Name != "deny" || got.Passed || got.Err == nil || !got.Internal {
+			t.Fatalf("unexpected policy event: %#v", got)
+		}
+	})
+}

runners.go

@@ -7,142 +7,167 @@ import (
 
 // 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
+type RunnerFn[T AppData] 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().
+// Runners are configured using builder methods Async and Every. Once the
-// Once Execute() is called, the Runner should not be modified.
+// bot's runtime has started executing the runner, it should not be modified.
 //
 // Execution semantics:
-//   - onetime=true, async=false: Run once synchronously (blocks).
+//   - every=0, async=true:  Run once in a goroutine (non-blocking, default).
-//   - onetime=true, async=true:  Run once in a goroutine (non-blocking).
+//   - every=0, async=false: Run once synchronously (blocks runtime startup).
-//   - onetime=false, async=true: Run repeatedly in a goroutine with timeout.
+//   - every>0, async=true:  Run repeatedly in a goroutine with the given interval.
-//   - onetime=false, async=false: Invalid configuration — ignored with warning.
+//   - every>0, async=false: Invalid configuration — skipped with a warning.
-type Runner[T DbContext] struct {
+type Runner[T AppData] struct {
-	name    string        // Human-readable name for logging
+	name  string        // Human-readable name for logging
-	onetime bool          // If true, runs once; if false, runs periodically
+	async bool          // If true, runs in a goroutine; else, runs synchronously
-	async   bool          // If true, runs in a goroutine; else, runs synchronously
+	every time.Duration // Interval between periodic executions; zero means one-shot
-	timeout time.Duration // Duration to wait between periodic executions (ignored if onetime=true)
+	fn    RunnerFn[T]   // The function to execute
-	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.
+// The default configuration is async=true and every=0, i.e. a one-shot
-// DO NOT call builder methods concurrently or after Execute().
+// goroutine that fires once when the bot runtime starts. Use Async and Every
-func NewRunner[T DbContext](name string, fn RunnerFn[T]) Runner[T] {
+// to customize this. Do not call builder methods concurrently or after the
+// bot runtime has begun executing runners.
+func NewRunner[T AppData](name string, fn RunnerFn[T]) Runner[T] {
 	return Runner[T]{
-		name:    name,
+		name:  name,
-		fn:      fn,
+		fn:    fn,
-		async:   true, // Default: run asynchronously
+		async: true,
-		timeout: 0,    // Default: no timeout (ignored if onetime=true)
+		every: 0,
 	}
 }
 
-// Onetime sets whether the runner executes once or repeatedly.
-// If true, the runner runs only once.
-// If false, the runner runs in a loop with the configured timeout.
-func (r Runner[T]) Onetime(onetime bool) Runner[T] {
-	r.onetime = onetime
-	return r
-}
-
 // 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.
+// Note: periodic runners (Every > 0) require async=true and are skipped with
+// a warning when async=false.
 func (r Runner[T]) Async(async bool) Runner[T] {
 	r.async = async
 	return r
 }
 
-// Timeout sets the duration to wait between repeated executions for
+// Every sets the interval between repeated executions of a periodic runner.
-// non-onetime runners.
 //
-// If onetime=true, this value is ignored.
+// A zero value (the default) keeps the runner one-shot. A positive value
-// If onetime=false and async=true, this timeout determines the sleep interval
+// schedules the runner to fire repeatedly with the given interval and
-// between loop iterations.
+// requires async=true; periodic sync runners are skipped with a warning.
-//
+func (r Runner[T]) Every(timeout time.Duration) Runner[T] {
-// A zero value (time.Duration(0)) is allowed but may trigger a warning
+	r.every = timeout
-// 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 with context-based lifecycle management.
 //
-// It logs warnings for misconfigured runners:
+// Execution semantics by configuration:
-//   - Sync, non-onetime runners are skipped (invalid configuration).
+//   - every=0, async=true:  Runs once in a goroutine (fire and forget).
-//   - Background (non-onetime, async) runners without a timeout trigger a warning.
+//   - every=0, async=false: Runs once synchronously; warns if slower than 2 seconds.
-//
+//   - every>0, async=true:  Runs in a loop with the configured interval until ctx.Done().
-// Execution logic:
+//   - every>0, async=false: Skipped with a warning (invalid configuration).
-//   - onetime + async: Runs once in a goroutine.
-//   - onetime + sync:  Runs once synchronously; warns if slower than 2 seconds.
-//   - !onetime + async: Runs in a loop with timeout between iterations until ctx.Done().
-//   - !onetime + sync: Skipped with warning.
 //
 // Background runners listen for ctx.Done() and gracefully shut down when the context is canceled.
 //
-// This method is typically called once during bot startup in RunWithContext.
+// This method is typically called once during bot startup from RunWithContext or
+// RunWebhookWithContext.
 func (bot *Bot[T]) ExecRunners(ctx context.Context) {
 	bot.logger.Infoln("Executing runners...")
 	for _, runner := range bot.runners {
-		// Validate configuration
+		if runner.every > 0 && !runner.async {
-		if !runner.onetime && !runner.async {
+			bot.logger.Warnf("Runner %q is periodic but sync; skipping (use Async(true))\n", runner.name)
-			bot.logger.Warnf("Runner %s not onetime, but sync — skipping\n", runner.name)
-			continue
-		}
-		if !runner.onetime && runner.async && runner.timeout == 0 {
-			bot.logger.Warnf("Background runner \"%s\" has no timeout — skipping\n", runner.name)
 			continue
 		}
 
-		if runner.onetime && runner.async {
+		if runner.every == 0 && runner.async {
 			// One-time async: fire and forget
 			bot.runnerOnceWG.Add(1)
 			go func(r Runner[T]) {
 				defer bot.runnerOnceWG.Done()
+				startedAt := time.Now()
 				err := r.fn(bot)
+				bot.safeEmitEvent(ctx, RunnerFinishedEvent{
+					Name:     r.name,
+					Duration: time.Since(startedAt),
+					Err:      err,
+				})
 				if err != nil {
+					bot.safeEmitEvent(ctx, ErrorEvent{
+						Plugin:      "bot",
+						HandlerKind: HandlerRunnerKind,
+						HandlerName: r.name,
+						Err:         err,
+						UserFacing:  false,
+					})
 					bot.logger.Warnf("Runner %s failed: %s\n", r.name, err)
 				}
 			}(runner)
-		} else if runner.onetime && !runner.async {
+		} else if runner.every == 0 && !runner.async {
 			// One-time sync: block until done
 			t := time.Now()
 			err := runner.fn(bot)
+			elapsed := time.Since(t)
+			bot.safeEmitEvent(ctx, RunnerFinishedEvent{
+				Name:     runner.name,
+				Duration: elapsed,
+				Err:      err,
+			})
 			if err != nil {
+				bot.safeEmitEvent(ctx, ErrorEvent{
+					Plugin:      "bot",
+					HandlerKind: HandlerRunnerKind,
+					HandlerName: runner.name,
+					Err:         err,
+					UserFacing:  false,
+				})
 				bot.logger.Warnf("Runner %s failed: %s\n", runner.name, err)
 			}
-			elapsed := time.Since(t)
 			if elapsed > time.Second*2 {
 				bot.logger.Warnf("Runner %s too slow. Elapsed time %v >= 2s\n", runner.name, elapsed)
 			}
-		} else if !runner.onetime && runner.async {
+		} else if runner.every > 0 && runner.async {
 			// Background loop: periodic execution with graceful shutdown
 			bot.runnerBgWG.Add(1)
 			go func(r Runner[T]) {
 				defer bot.runnerBgWG.Done()
-				ticker := time.NewTicker(r.timeout)
+				ticker := time.NewTicker(r.every)
 				defer ticker.Stop()
 				for {
 					select {
 					case <-ctx.Done():
 						return
 					case <-ticker.C:
-						err := r.fn(bot)
+					}
-						if err != nil {
+					// When both ctx.Done() and ticker.C are ready at the same
-							bot.logger.Warnf("Runner %s failed: %s\n", r.name, err)
+					// time, Go's select picks one at random. Re-check ctx so a
-						}
+					// late tick after cancellation does not fire one extra
+					// invocation past shutdown.
+					if ctx.Err() != nil {
+						return
+					}
+					startedAt := time.Now()
+					err := r.fn(bot)
+					bot.safeEmitEvent(ctx, RunnerFinishedEvent{
+						Name:     r.name,
+						Duration: time.Since(startedAt),
+						Err:      err,
+					})
+					if err != nil {
+						bot.safeEmitEvent(ctx, ErrorEvent{
+							Plugin:      "bot",
+							HandlerKind: HandlerRunnerKind,
+							HandlerName: r.name,
+							Err:         err,
+							UserFacing:  false,
+						})
+						bot.logger.Warnf("Runner %s failed: %s\n", r.name, err)
 					}
 				}
 			}(runner)
 		}
-		// Note: !onetime && !async is already skipped above
 	}
 }

runners_test.go

@@ -2,22 +2,27 @@ package laniakea
 
 import (
 	"context"
+	"errors"
 	"sync/atomic"
 	"testing"
 	"time"
 
-	"git.nix13.pw/scuroneko/slog"
+	"git.scuroneko.dev/scuroneko/sneklog/v2"
 )
 
-func TestExecRunnersRunsOnetimeSyncRunner(t *testing.T) {
+type runnerObserver struct {
+	recordingObserver
+}
+
+func TestExecRunnersRunsOnceSyncRunner(t *testing.T) {
 	var calls atomic.Int32
-	bot := &Bot[NoDB]{
+	bot := &Bot[NoData]{
-		logger: slog.CreateLogger(),
+		logger: sneklog.NewLogger(),
-		runners: []Runner[NoDB]{
+		runners: []Runner[NoData]{
-			NewRunner("sync-once", func(*Bot[NoDB]) error {
+			NewRunner("sync-once", func(*Bot[NoData]) error {
 				calls.Add(1)
 				return nil
-			}).Onetime(true).Async(false),
+			}).Async(false),
 		},
 	}
 
@@ -33,15 +38,15 @@ func TestExecRunnersStopsBackgroundRunnerOnCancel(t *testing.T) {
 	triggered := make(chan struct{}, 1)
 	ctx, cancel := context.WithCancel(context.Background())
 
-	bot := &Bot[NoDB]{
+	bot := &Bot[NoData]{
-		logger: slog.CreateLogger(),
+		logger: sneklog.NewLogger(),
-		runners: []Runner[NoDB]{
+		runners: []Runner[NoData]{
-			NewRunner("background", func(*Bot[NoDB]) error {
+			NewRunner("background", func(*Bot[NoData]) error {
 				if calls.Add(1) == 1 {
 					triggered <- struct{}{}
 				}
 				return nil
-			}).Timeout(5 * time.Millisecond),
+			}).Every(5 * time.Millisecond),
 		},
 	}
 
@@ -60,3 +65,33 @@ func TestExecRunnersStopsBackgroundRunnerOnCancel(t *testing.T) {
 		t.Fatal("expected background runner to be called at least once")
 	}
 }
+
+func TestExecRunnersEmitObserverEvents(t *testing.T) {
+	observer := &runnerObserver{}
+	wantErr := errors.New("runner failed")
+
+	bot := &Bot[NoData]{
+		logger:   sneklog.NewLogger(),
+		observer: observer,
+		runners: []Runner[NoData]{
+			NewRunner("sync-once", func(*Bot[NoData]) error {
+				return wantErr
+			}).Async(false),
+		},
+	}
+
+	bot.ExecRunners(context.Background())
+
+	if len(observer.runners) != 1 {
+		t.Fatalf("expected one runner-finished event, got %d", len(observer.runners))
+	}
+	if got := observer.runners[0]; got.Name != "sync-once" || !errors.Is(got.Err, wantErr) {
+		t.Fatalf("unexpected runner-finished event: %#v", got)
+	}
+	if len(observer.errors) != 1 {
+		t.Fatalf("expected one error event, got %d", len(observer.errors))
+	}
+	if got := observer.errors[0]; got.HandlerKind != HandlerRunnerKind || got.HandlerName != "sync-once" || !errors.Is(got.Err, wantErr) {
+		t.Fatalf("unexpected runner error event: %#v", got)
+	}
+}

scene.go

@@ -0,0 +1,267 @@
+package laniakea
+
+import (
+	"encoding/json"
+	"maps"
+	"sync"
+)
+
+// SceneHandler handles a scene step, scene command, or fallback message.
+type SceneHandler[T any] func(ctx *SceneContext, db T) (SceneResult, error)
+
+// Scene defines a multi-step conversational flow.
+type Scene[T any] struct {
+	name       string
+	scope      SceneScope
+	entry      string
+	pluginName string
+
+	steps    map[string]SceneHandler[T]
+	commands map[string]SceneHandler[T]
+	payloads map[string]SceneHandler[T]
+	message  SceneHandler[T]
+}
+
+// NewScene creates a new scene with user-chat scope by default.
+func NewScene[T any](name string) *Scene[T] {
+	return &Scene[T]{
+		name:     name,
+		scope:    SceneScopeUserChat,
+		entry:    "",
+		steps:    make(map[string]SceneHandler[T]),
+		commands: make(map[string]SceneHandler[T]),
+		payloads: make(map[string]SceneHandler[T]),
+		message:  nil,
+	}
+}
+
+// SetScope changes how scene sessions are keyed and shared.
+func (s *Scene[T]) SetScope(scope SceneScope) *Scene[T] {
+	s.scope = scope
+	return s
+}
+
+// SetEntry sets the initial step entered by MessageContext.EnterScene.
+func (s *Scene[T]) SetEntry(step string) *Scene[T] {
+	s.entry = step
+	return s
+}
+
+func (s *Scene[T]) setPluginName(name string) *Scene[T] {
+	s.pluginName = name
+	return s
+}
+
+// OnStep registers a handler for a named scene step.
+func (s *Scene[T]) OnStep(step string, handler SceneHandler[T]) *Scene[T] {
+	s.steps[step] = handler
+	return s
+}
+
+// OnCommand registers a command handler active while the scene is running.
+func (s *Scene[T]) OnCommand(cmd string, handler SceneHandler[T]) *Scene[T] {
+	s.commands[cmd] = handler
+	return s
+}
+
+// OnPayload registers a callback payload handler active while the scene is running.
+func (s *Scene[T]) OnPayload(cmd string, handler SceneHandler[T]) *Scene[T] {
+	s.payloads[cmd] = handler
+	return s
+}
+
+// OnMessage registers a fallback handler used when no scene command or step matches.
+func (s *Scene[T]) OnMessage(handler SceneHandler[T]) *Scene[T] {
+	s.message = handler
+	return s
+}
+
+func (s *Scene[T]) executeCommand(cmd string, ctx *SceneContext, db T) (SceneResult, bool, error) {
+	handler, ok := s.commands[cmd]
+	if !ok {
+		return SceneResult{}, false, nil
+	}
+	result, err := handler(ctx, db)
+	return result, true, err
+}
+func (s *Scene[T]) executePayload(cmd string, ctx *SceneContext, db T) (SceneResult, bool, error) {
+	handler, ok := s.payloads[cmd]
+	if !ok {
+		return SceneResult{}, false, nil
+	}
+	result, err := handler(ctx, db)
+	return result, true, err
+}
+func (s *Scene[T]) executeStep(step string, ctx *SceneContext, db T) (SceneResult, bool, error) {
+	handler, ok := s.steps[step]
+	if !ok {
+		return SceneResult{}, false, nil
+	}
+	result, err := handler(ctx, db)
+	return result, true, err
+}
+func (s *Scene[T]) executeMessage(ctx *SceneContext, db T) (SceneResult, bool, error) {
+	if s.message == nil {
+		return SceneResult{}, false, nil
+	}
+	result, err := s.message(ctx, db)
+	return result, true, err
+}
+
+func (s *Scene[T]) clone() *Scene[T] {
+	if s == nil {
+		return nil
+	}
+
+	cloned := *s
+	cloned.steps = make(map[string]SceneHandler[T], len(s.steps))
+	cloned.commands = make(map[string]SceneHandler[T], len(s.commands))
+	cloned.payloads = make(map[string]SceneHandler[T], len(s.payloads))
+
+	maps.Copy(cloned.steps, s.steps)
+	maps.Copy(cloned.commands, s.commands)
+	maps.Copy(cloned.payloads, s.payloads)
+
+	return &cloned
+}
+
+// SceneSession stores the active scene state for one session key.
+type SceneSession struct {
+	// Scene is the registered scene name for the active session.
+	Scene string
+	// Step is the current step name inside the active scene.
+	Step string
+	// data stores opaque session payload bytes, typically JSON.
+	data []byte
+}
+
+// SetData stores arbitrary opaque session data.
+func (s *SceneSession) SetData(data []byte) {
+	s.data = data
+}
+
+// GetData returns the raw session data payload.
+func (s *SceneSession) GetData() []byte {
+	return s.data
+}
+
+// HasData reports whether the session has a non-empty data payload.
+func (s *SceneSession) HasData() bool {
+	return len(s.data) > 0
+}
+
+// ClearData removes any stored session data.
+func (s *SceneSession) ClearData() {
+	s.data = nil
+}
+
+// BindData unmarshals the stored JSON payload into v.
+func (s *SceneSession) BindData(v any) error {
+	if len(s.data) == 0 {
+		return nil
+	}
+	return json.Unmarshal(s.data, v)
+}
+
+// SaveData marshals v as JSON and stores it in the session.
+func (s *SceneSession) SaveData(v any) error {
+	data, err := json.Marshal(v)
+	if err != nil {
+		return err
+	}
+	s.data = data
+	return nil
+}
+
+// SessionStore persists scene sessions by key.
+type SessionStore interface {
+	Get(key string) (SceneSession, error)
+	Set(key string, session SceneSession) error
+	Delete(key string) error
+}
+
+// MemorySessionStore stores scene sessions in memory.
+type MemorySessionStore struct {
+	store map[string]SceneSession
+	mu    sync.RWMutex
+}
+
+// NewMemorySessionStore creates an empty in-memory session store.
+func NewMemorySessionStore() *MemorySessionStore {
+	return &MemorySessionStore{
+		store: make(map[string]SceneSession),
+	}
+}
+
+// Get returns the session stored under key, or the zero session when absent.
+func (s *MemorySessionStore) Get(key string) (SceneSession, error) {
+	s.mu.RLock()
+	defer s.mu.RUnlock()
+	if session, ok := s.store[key]; ok {
+		return session, nil
+	}
+	return SceneSession{}, nil
+}
+
+// Set stores session under key.
+func (s *MemorySessionStore) Set(key string, session SceneSession) error {
+	s.mu.Lock()
+	s.store[key] = session
+	s.mu.Unlock()
+	return nil
+}
+
+// Delete removes the session stored under key.
+func (s *MemorySessionStore) Delete(key string) error {
+	s.mu.Lock()
+	delete(s.store, key)
+	s.mu.Unlock()
+	return nil
+}
+
+// SceneResult describes how scene execution should proceed after a handler returns.
+type SceneResult struct {
+	Action SceneAction
+	Next   string
+}
+
+// SceneAction controls how the bot updates scene state after a handler returns.
+type SceneAction int
+
+const (
+	// SceneActionStay keeps the current scene and step active.
+	SceneActionStay SceneAction = iota
+	// SceneActionNext moves the session to another named step.
+	SceneActionNext
+	// SceneActionExit removes the current scene session.
+	SceneActionExit
+	// SceneActionPass lets normal bot routing continue after the scene handler.
+	SceneActionPass
+)
+
+// SceneScope defines how scene sessions are keyed.
+type SceneScope int
+
+const (
+	// SceneScopeUser shares a scene across all chats for one user.
+	SceneScopeUser SceneScope = iota
+	// SceneScopeChat shares a scene across all users in one chat.
+	SceneScopeChat
+	// SceneScopeUserChat isolates a scene per user-chat pair.
+	SceneScopeUserChat
+)
+
+type sceneRuntime interface {
+	findScene(name string) (*sceneMeta, bool)
+	getSession(key string) (SceneSession, error)
+	setSession(key string, session SceneSession) error
+	deleteSession(key string) error
+	findSceneSession(ctx *MessageContext) (string, SceneSession, error)
+}
+
+type sceneMeta struct {
+	Name  string
+	Scope SceneScope
+	Entry string
+	Steps map[string]struct{}
+}

scene_context.go

@@ -0,0 +1,41 @@
+package laniakea
+
+// SceneContext wraps MessageContext with scene session state for scene handlers.
+type SceneContext struct {
+	*MessageContext
+	sess SceneSession
+	key  string
+}
+
+// Next advances the current scene to step.
+func (ctx *SceneContext) Next(step string) SceneResult {
+	return SceneResult{
+		Action: SceneActionNext,
+		Next:   step,
+	}
+}
+
+// Stay keeps the current scene step active.
+func (ctx *SceneContext) Stay() SceneResult {
+	return SceneResult{Action: SceneActionStay}
+}
+
+// Exit leaves the current scene.
+func (ctx *SceneContext) Exit() SceneResult {
+	return SceneResult{Action: SceneActionExit}
+}
+
+// Pass stops scene handling and lets normal routing continue.
+func (ctx *SceneContext) Pass() SceneResult {
+	return SceneResult{Action: SceneActionPass}
+}
+
+// BindData unmarshals the current scene session payload into v.
+func (ctx *SceneContext) BindData(v any) error {
+	return ctx.sess.BindData(v)
+}
+
+// SaveData marshals v and stores it in the current scene session payload.
+func (ctx *SceneContext) SaveData(v any) error {
+	return ctx.sess.SaveData(v)
+}

scene_handler.go

@@ -0,0 +1,296 @@
+package laniakea
+
+import (
+	"errors"
+	"fmt"
+	"strings"
+	"time"
+)
+
+func (bot *Bot[T]) tryHandleScene(ctx *MessageContext) (bool, error) {
+	key, session, err := bot.findSceneSession(ctx)
+	if err != nil {
+		if errors.Is(err, ErrCantFindSession) {
+			return false, nil
+		}
+		return false, err
+	}
+	if session.Scene == "" {
+		return false, nil
+	}
+
+	for _, plugin := range bot.plugins {
+		scene, ok := plugin.scenes[session.Scene]
+		if !ok {
+			continue
+		}
+		if scene.pluginName != "" && scene.pluginName != plugin.name {
+			continue
+		}
+		if !plugin.executeMiddlewares(ctx, bot.appData) {
+			return false, nil
+		}
+		sceneCtx := &SceneContext{
+			MessageContext: ctx,
+			sess:           session,
+			key:            key,
+		}
+
+		return bot.executeScene(sceneCtx, scene)
+	}
+	return false, ErrSceneNotFound
+}
+
+func (bot *Bot[T]) executeScene(ctx *SceneContext, scene *Scene[T]) (bool, error) {
+	if ctx.MessageContext == nil || ctx.sess.Scene == "" {
+		return false, nil
+	}
+
+	var text string
+	if ctx.Msg != nil {
+		text = ctx.Msg.Text
+		if text == "" {
+			text = ctx.Msg.Caption
+		}
+	}
+
+	text = strings.TrimSpace(text)
+	prefix, cmd, args := bot.parseCommand(text)
+	if cmd != "" {
+		ctx.Prefix = prefix
+		ctx.Text = args
+		ctx.Args = strings.Fields(args)
+
+		if _, ok := scene.commands[cmd]; ok {
+			startTime := time.Now()
+			bot.emitSceneStarted(ctx, scene, HandlerSceneCommandKind, cmd)
+			res, _, err := scene.executeCommand(cmd, ctx, bot.appData)
+			if err != nil {
+				bot.emitSceneFinished(ctx, scene, HandlerSceneCommandKind, cmd, startTime, err)
+				bot.emitSceneError(ctx, scene, HandlerSceneCommandKind, cmd, err)
+				return false, err
+			}
+			from := ctx.sess.Step
+			ok, err := bot.applySceneResult(scene, ctx, res)
+			bot.emitSceneFinished(ctx, scene, HandlerSceneCommandKind, cmd, startTime, err)
+			if err != nil {
+				bot.emitSceneError(ctx, scene, HandlerSceneCommandKind, cmd, err)
+			}
+			if ok {
+				bot.emitSceneTransition(ctx, scene, from, res)
+			}
+			return ok, err
+		}
+
+		// Unmatched slash-commands should continue through normal bot command routing
+		// instead of also triggering the active scene step or fallback handler.
+		return false, nil
+	}
+
+	query := ctx.Update.CallbackQuery
+	if query != nil {
+		data, err := bot.decodePayload(query.Data)
+		if err != nil {
+			return false, err
+		}
+		ctx.Args = data.Args
+		cmd := data.Command
+		if _, ok := scene.payloads[cmd]; ok {
+			startTime := time.Now()
+			bot.emitSceneStarted(ctx, scene, HandlerScenePayloadKind, cmd)
+			res, _, err := scene.executePayload(cmd, ctx, bot.appData)
+			if err != nil {
+				bot.emitSceneFinished(ctx, scene, HandlerScenePayloadKind, cmd, startTime, err)
+				bot.emitSceneError(ctx, scene, HandlerScenePayloadKind, cmd, err)
+				return false, err
+			}
+			from := ctx.sess.Step
+			ok, err := bot.applySceneResult(scene, ctx, res)
+			bot.emitSceneFinished(ctx, scene, HandlerScenePayloadKind, cmd, startTime, err)
+			if err != nil {
+				bot.emitSceneError(ctx, scene, HandlerScenePayloadKind, cmd, err)
+			}
+			if ok {
+				bot.emitSceneTransition(ctx, scene, from, res)
+			}
+			return ok, err
+		}
+
+		// Unmatched payloads should not trigger the active scene step or fallback handler.
+		// This allows using payloads for other bot features like pagination without interfering with active scenes.
+		return false, nil
+	}
+
+	ctx.Text = text
+	ctx.Args = nil
+	ctx.Prefix = ""
+	if ctx.sess.Step != "" {
+		step := ctx.sess.Step
+		if _, ok := scene.steps[step]; ok {
+			startTime := time.Now()
+			bot.emitSceneStarted(ctx, scene, HandlerSceneStepKind, step)
+			res, _, err := scene.executeStep(step, ctx, bot.appData)
+			if err != nil {
+				bot.emitSceneFinished(ctx, scene, HandlerSceneStepKind, step, startTime, err)
+				bot.emitSceneError(ctx, scene, HandlerSceneStepKind, step, err)
+				return false, err
+			}
+			from := step
+			ok, err := bot.applySceneResult(scene, ctx, res)
+			bot.emitSceneFinished(ctx, scene, HandlerSceneStepKind, step, startTime, err)
+			if err != nil {
+				bot.emitSceneError(ctx, scene, HandlerSceneStepKind, from, err)
+			}
+			if ok {
+				bot.emitSceneTransition(ctx, scene, from, res)
+			}
+			return ok, err
+		}
+	}
+
+	if scene.message != nil {
+		startTime := time.Now()
+		bot.emitSceneStarted(ctx, scene, HandlerSceneMessageKind, "message_fallback")
+		res, _, err := scene.executeMessage(ctx, bot.appData)
+		if err != nil {
+			bot.emitSceneFinished(ctx, scene, HandlerSceneMessageKind, "message_fallback", startTime, err)
+			bot.emitSceneError(ctx, scene, HandlerSceneMessageKind, "message_fallback", err)
+			return false, err
+		}
+		from := ctx.sess.Step
+		ok, err := bot.applySceneResult(scene, ctx, res)
+		bot.emitSceneFinished(ctx, scene, HandlerSceneMessageKind, "message_fallback", startTime, err)
+		if err != nil {
+			bot.emitSceneError(ctx, scene, HandlerSceneMessageKind, "message_fallback", err)
+		}
+		if ok {
+			bot.emitSceneTransition(ctx, scene, from, res)
+		}
+		return ok, err
+	}
+
+	return false, nil
+}
+
+func (bot *Bot[T]) emitSceneStarted(ctx *SceneContext, scene *Scene[T], kind HandlerEventKind, name string) {
+	bot.safeEmitEvent(ctx.Context(), HandlerStartedEvent{
+		UpdateID:    ctx.Update.UpdateID,
+		UpdateType:  ctx.Update.Type,
+		Plugin:      scene.pluginName,
+		HandlerKind: kind,
+		HandlerName: name,
+		FromID:      ctx.FromID,
+		ChatID:      ctx.ChatID,
+	})
+}
+
+func (bot *Bot[T]) emitSceneFinished(ctx *SceneContext, scene *Scene[T], kind HandlerEventKind, name string, startedAt time.Time, err error) {
+	bot.safeEmitEvent(ctx.Context(), HandlerFinishedEvent{
+		UpdateID:    ctx.Update.UpdateID,
+		UpdateType:  ctx.Update.Type,
+		Plugin:      scene.pluginName,
+		HandlerKind: kind,
+		HandlerName: name,
+		FromID:      ctx.FromID,
+		ChatID:      ctx.ChatID,
+		Duration:    time.Since(startedAt),
+		Err:         err,
+		UserFacing:  IsUserError(err),
+	})
+}
+
+func (bot *Bot[T]) emitSceneError(ctx *SceneContext, scene *Scene[T], kind HandlerEventKind, name string, err error) {
+	bot.safeEmitEvent(ctx.Context(), ErrorEvent{
+		UpdateID:    ctx.Update.UpdateID,
+		UpdateType:  ctx.Update.Type,
+		Plugin:      scene.pluginName,
+		HandlerKind: kind,
+		HandlerName: name,
+		FromID:      ctx.FromID,
+		ChatID:      ctx.ChatID,
+		Err:         err,
+		UserFacing:  IsUserError(err),
+	})
+}
+
+func (bot *Bot[T]) emitSceneTransition(ctx *SceneContext, scene *Scene[T], from string, result SceneResult) {
+	if result.Action == SceneActionPass {
+		return
+	}
+
+	var to string
+	switch result.Action {
+	case SceneActionNext:
+		to = result.Next
+	case SceneActionExit:
+		to = ""
+	default:
+		to = from
+	}
+
+	bot.safeEmitEvent(ctx.Context(), SceneTransitionEvent{
+		Plugin: scene.pluginName,
+		Scene:  scene.name,
+		From:   from,
+		To:     to,
+		Action: result.Action,
+		FromID: ctx.FromID,
+		ChatID: ctx.ChatID,
+	})
+}
+
+func (bot *Bot[T]) applySceneResult(scene *Scene[T], ctx *SceneContext, result SceneResult) (bool, error) {
+	switch result.Action {
+	case SceneActionStay:
+		if err := bot.sessionStore.Set(ctx.key, ctx.sess); err != nil {
+			return false, err
+		}
+		return true, nil
+	case SceneActionNext:
+		if result.Next == "" {
+			return false, ErrSceneStepNotFound
+		}
+		if _, ok := scene.steps[result.Next]; !ok {
+			return false, ErrSceneStepNotFound
+		}
+		ctx.sess.Step = result.Next
+		if err := bot.sessionStore.Set(ctx.key, ctx.sess); err != nil {
+			return false, err
+		}
+		return true, nil
+	case SceneActionExit:
+		if err := bot.sessionStore.Delete(ctx.key); err != nil {
+			return false, err
+		}
+		return true, nil
+	case SceneActionPass:
+		return false, nil
+	default:
+		return false, nil
+	}
+}
+func buildSceneKey(scope SceneScope, ctx *MessageContext) (string, bool) {
+	if ctx == nil {
+		return "", false
+	}
+
+	switch scope {
+	case SceneScopeUserChat:
+		if ctx.Msg == nil || ctx.Msg.Chat == nil || ctx.FromID == 0 {
+			return "", false
+		}
+		return fmt.Sprintf("user_id:%d:chat_id:%d", ctx.FromID, ctx.Msg.Chat.ID), true
+	case SceneScopeChat:
+		if ctx.Msg == nil || ctx.Msg.Chat == nil {
+			return "", false
+		}
+		return fmt.Sprintf("chat_id:%d", ctx.Msg.Chat.ID), true
+	case SceneScopeUser:
+		if ctx.FromID == 0 {
+			return "", false
+		}
+		return fmt.Sprintf("user_id:%d", ctx.FromID), true
+	default:
+		return "", false
+	}
+}

scene_test.go

@@ -0,0 +1,898 @@
+package laniakea
+
+import (
+	"context"
+	"errors"
+	"testing"
+
+	"git.scuroneko.dev/scuroneko/laniakea/tgapi"
+	"git.scuroneko.dev/scuroneko/sneklog/v2"
+)
+
+type failingSessionStore struct {
+	getErr    error
+	setErr    error
+	deleteErr error
+}
+
+func (s failingSessionStore) Get(string) (SceneSession, error) {
+	return SceneSession{}, s.getErr
+}
+
+func (s failingSessionStore) Set(string, SceneSession) error {
+	return s.setErr
+}
+
+func (s failingSessionStore) Delete(string) error {
+	return s.deleteErr
+}
+
+func TestPluginAddSceneRegistersScene(t *testing.T) {
+	plugin := NewPlugin[NoData]("wizard")
+	scene := NewScene[NoData]("signup")
+
+	plugin.AddScene(scene)
+
+	if got, ok := plugin.scenes["signup"]; !ok || got != scene {
+		t.Fatalf("scene was not registered in plugin: ok=%v got=%p want=%p", ok, got, scene)
+	}
+	if scene.pluginName != "wizard" {
+		t.Fatalf("unexpected plugin name on scene: got %q want %q", scene.pluginName, "wizard")
+	}
+}
+
+func TestBotAddPluginsPreservesScenesAndHandlesThem(t *testing.T) {
+	called := false
+
+	plugin := NewPlugin[NoData]("wizard")
+	plugin.Scene("signup").
+		SetEntry("start").
+		OnStep("start", func(ctx *SceneContext, db NoData) (SceneResult, error) {
+			called = true
+			if ctx.Text != "hello there" {
+				t.Fatalf("unexpected scene text: got %q want %q", ctx.Text, "hello there")
+			}
+			return ctx.Exit(), nil
+		})
+
+	bot := &Bot[NoData]{
+		logger:             sneklog.NewLogger(),
+		prefixes:           []string{"/"},
+		sessionStore:       NewMemorySessionStore(),
+		sceneScopePriority: []SceneScope{SceneScopeUserChat, SceneScopeChat, SceneScopeUser},
+	}
+	bot.AddPlugins(plugin)
+
+	sceneMeta, ok := bot.findScene("signup")
+	if !ok {
+		t.Fatal("expected scene metadata to be available after plugin registration")
+	}
+	if sceneMeta.Entry != "start" {
+		t.Fatalf("unexpected scene entry: got %q want %q", sceneMeta.Entry, "start")
+	}
+
+	enterCtx := &MessageContext{
+		Msg:          &tgapi.Message{Chat: &tgapi.Chat{ID: 100, Type: tgapi.ChatTypePrivate}},
+		FromID:       42,
+		sceneRuntime: bot,
+	}
+	if err := enterCtx.EnterScene("signup"); err != nil {
+		t.Fatalf("EnterScene returned error: %v", err)
+	}
+
+	bot.handle(context.Background(), &tgapi.Update{
+		UpdateID: 1,
+		Type:     tgapi.UpdateTypeMessage,
+		Message: &tgapi.Message{
+			MessageID: 7,
+			Text:      "hello there",
+			Chat:      &tgapi.Chat{ID: 100, Type: tgapi.ChatTypePrivate},
+			From:      &tgapi.User{ID: 42},
+		},
+	})
+
+	if !called {
+		t.Fatal("expected scene step handler to be called")
+	}
+
+	lookupCtx := &MessageContext{
+		Msg:    &tgapi.Message{Chat: &tgapi.Chat{ID: 100, Type: tgapi.ChatTypePrivate}},
+		FromID: 42,
+	}
+	if _, session, err := bot.findSceneSession(lookupCtx); err == nil && session.Scene != "" {
+		t.Fatalf("expected scene session to be removed after exit, got %#v", session)
+	}
+}
+
+func TestBuildSceneKeyRejectsMissingContextFields(t *testing.T) {
+	tests := []struct {
+		name  string
+		scope SceneScope
+		ctx   *MessageContext
+	}{
+		{
+			name:  "nil context",
+			scope: SceneScopeUserChat,
+			ctx:   nil,
+		},
+		{
+			name:  "missing message for chat scope",
+			scope: SceneScopeChat,
+			ctx:   &MessageContext{},
+		},
+		{
+			name:  "missing from id for user scope",
+			scope: SceneScopeUser,
+			ctx:   &MessageContext{},
+		},
+		{
+			name:  "missing from id for user chat scope",
+			scope: SceneScopeUserChat,
+			ctx: &MessageContext{
+				Msg: &tgapi.Message{Chat: &tgapi.Chat{ID: 100, Type: tgapi.ChatTypePrivate}},
+			},
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			if key, ok := buildSceneKey(tt.scope, tt.ctx); ok || key != "" {
+				t.Fatalf("expected invalid scene key, got key=%q ok=%v", key, ok)
+			}
+		})
+	}
+}
+
+func TestEnterSceneRejectsMissingEntryConfiguration(t *testing.T) {
+	t.Run("empty entry", func(t *testing.T) {
+		plugin := NewPlugin[NoData]("wizard")
+		plugin.Scene("signup")
+
+		bot := &Bot[NoData]{
+			logger:             sneklog.NewLogger(),
+			sessionStore:       NewMemorySessionStore(),
+			sceneScopePriority: []SceneScope{SceneScopeUserChat, SceneScopeChat, SceneScopeUser},
+		}
+		bot.AddPlugins(plugin)
+
+		ctx := &MessageContext{
+			Msg:          &tgapi.Message{Chat: &tgapi.Chat{ID: 100, Type: tgapi.ChatTypePrivate}},
+			FromID:       42,
+			sceneRuntime: bot,
+		}
+
+		err := ctx.EnterScene("signup")
+		if !errors.Is(err, ErrSceneEntryNotSet) {
+			t.Fatalf("expected ErrSceneEntryNotSet, got %v", err)
+		}
+	})
+
+	t.Run("missing entry step", func(t *testing.T) {
+		plugin := NewPlugin[NoData]("wizard")
+		plugin.Scene("signup").SetEntry("start")
+
+		bot := &Bot[NoData]{
+			logger:             sneklog.NewLogger(),
+			sessionStore:       NewMemorySessionStore(),
+			sceneScopePriority: []SceneScope{SceneScopeUserChat, SceneScopeChat, SceneScopeUser},
+		}
+		bot.AddPlugins(plugin)
+
+		ctx := &MessageContext{
+			Msg:          &tgapi.Message{Chat: &tgapi.Chat{ID: 100, Type: tgapi.ChatTypePrivate}},
+			FromID:       42,
+			sceneRuntime: bot,
+		}
+
+		err := ctx.EnterScene("signup")
+		if !errors.Is(err, ErrSceneStepNotFound) {
+			t.Fatalf("expected ErrSceneStepNotFound, got %v", err)
+		}
+	})
+}
+
+func TestSceneContextMethodsRequireRuntime(t *testing.T) {
+	ctx := &MessageContext{}
+
+	if err := ctx.EnterScene("signup"); !errors.Is(err, ErrSceneRuntimeNil) {
+		t.Fatalf("expected ErrSceneRuntimeNil from EnterScene, got %v", err)
+	}
+	if err := ctx.EnterSceneStep("signup", "start"); !errors.Is(err, ErrSceneRuntimeNil) {
+		t.Fatalf("expected ErrSceneRuntimeNil from EnterSceneStep, got %v", err)
+	}
+	if err := ctx.ExitScene(); !errors.Is(err, ErrSceneRuntimeNil) {
+		t.Fatalf("expected ErrSceneRuntimeNil from ExitScene, got %v", err)
+	}
+}
+
+func TestSceneCommandHandlerRunsBeforeStep(t *testing.T) {
+	sceneCommandCalled := false
+	stepCalled := false
+
+	plugin := NewPlugin[NoData]("wizard")
+	plugin.Scene("signup").
+		SetEntry("start").
+		OnStep("start", func(ctx *SceneContext, db NoData) (SceneResult, error) {
+			stepCalled = true
+			return ctx.Stay(), nil
+		}).
+		OnCommand("cancel", func(ctx *SceneContext, db NoData) (SceneResult, error) {
+			sceneCommandCalled = true
+			if ctx.Prefix != "/" {
+				t.Fatalf("unexpected prefix: got %q want /", ctx.Prefix)
+			}
+			if ctx.Text != "right now" {
+				t.Fatalf("unexpected scene command text: got %q want %q", ctx.Text, "right now")
+			}
+			if len(ctx.Args) != 2 || ctx.Args[0] != "right" || ctx.Args[1] != "now" {
+				t.Fatalf("unexpected scene command args: %#v", ctx.Args)
+			}
+			return ctx.Exit(), nil
+		})
+
+	bot := &Bot[NoData]{
+		logger:             sneklog.NewLogger(),
+		prefixes:           []string{"/"},
+		sessionStore:       NewMemorySessionStore(),
+		sceneScopePriority: []SceneScope{SceneScopeUserChat, SceneScopeChat, SceneScopeUser},
+	}
+	bot.AddPlugins(plugin)
+
+	enterCtx := &MessageContext{
+		Msg:          &tgapi.Message{Chat: &tgapi.Chat{ID: 100, Type: tgapi.ChatTypePrivate}},
+		FromID:       42,
+		sceneRuntime: bot,
+	}
+	if err := enterCtx.EnterScene("signup"); err != nil {
+		t.Fatalf("EnterScene returned error: %v", err)
+	}
+
+	bot.handle(context.Background(), &tgapi.Update{
+		UpdateID: 2,
+		Type:     tgapi.UpdateTypeMessage,
+		Message: &tgapi.Message{
+			MessageID: 8,
+			Text:      "/cancel right now",
+			Chat:      &tgapi.Chat{ID: 100, Type: tgapi.ChatTypePrivate},
+			From:      &tgapi.User{ID: 42},
+		},
+	})
+
+	if !sceneCommandCalled {
+		t.Fatal("expected scene command handler to be called")
+	}
+	if stepCalled {
+		t.Fatal("expected scene command to short-circuit the scene step")
+	}
+}
+
+func TestSceneCommandObserverEmitsLifecycleEvents(t *testing.T) {
+	observer := &recordingObserver{}
+	plugin := NewPlugin[NoData]("wizard")
+	plugin.Scene("signup").
+		SetEntry("start").
+		OnStep("start", func(ctx *SceneContext, db NoData) (SceneResult, error) {
+			return ctx.Stay(), nil
+		}).
+		OnCommand("cancel", func(ctx *SceneContext, db NoData) (SceneResult, error) {
+			return ctx.Exit(), nil
+		})
+
+	bot := &Bot[NoData]{
+		logger:             sneklog.NewLogger(),
+		prefixes:           []string{"/"},
+		sessionStore:       NewMemorySessionStore(),
+		sceneScopePriority: []SceneScope{SceneScopeUserChat, SceneScopeChat, SceneScopeUser},
+		observer:           observer,
+	}
+	bot.AddPlugins(plugin)
+
+	enterCtx := &MessageContext{
+		Msg:          &tgapi.Message{Chat: &tgapi.Chat{ID: 100, Type: tgapi.ChatTypePrivate}},
+		FromID:       42,
+		sceneRuntime: bot,
+	}
+	if err := enterCtx.EnterScene("signup"); err != nil {
+		t.Fatalf("EnterScene returned error: %v", err)
+	}
+
+	bot.handle(context.Background(), &tgapi.Update{
+		UpdateID: 22,
+		Type:     tgapi.UpdateTypeMessage,
+		Message: &tgapi.Message{
+			MessageID: 9,
+			Text:      "/cancel",
+			Chat:      &tgapi.Chat{ID: 100, Type: tgapi.ChatTypePrivate},
+			From:      &tgapi.User{ID: 42},
+		},
+	})
+
+	if len(observer.started) != 1 {
+		t.Fatalf("expected one scene started event, got %d", len(observer.started))
+	}
+	if got := observer.started[0]; got.HandlerKind != HandlerSceneCommandKind || got.HandlerName != "cancel" || got.Plugin != "wizard" {
+		t.Fatalf("unexpected scene started event: %#v", got)
+	}
+	if len(observer.finished) != 1 {
+		t.Fatalf("expected one scene finished event, got %d", len(observer.finished))
+	}
+	if got := observer.finished[0]; got.HandlerKind != HandlerSceneCommandKind || got.HandlerName != "cancel" || got.Plugin != "wizard" || got.Err != nil {
+		t.Fatalf("unexpected scene finished event: %#v", got)
+	}
+}
+
+func TestSceneStepObserverEmitsLifecycleEvents(t *testing.T) {
+	observer := &recordingObserver{}
+	plugin := NewPlugin[NoData]("wizard")
+	plugin.Scene("signup").
+		SetEntry("start").
+		OnStep("start", func(ctx *SceneContext, db NoData) (SceneResult, error) {
+			return ctx.Stay(), nil
+		})
+
+	bot := &Bot[NoData]{
+		logger:             sneklog.NewLogger(),
+		prefixes:           []string{"/"},
+		sessionStore:       NewMemorySessionStore(),
+		sceneScopePriority: []SceneScope{SceneScopeUserChat, SceneScopeChat, SceneScopeUser},
+		observer:           observer,
+	}
+	bot.AddPlugins(plugin)
+
+	enterCtx := &MessageContext{
+		Msg:          &tgapi.Message{Chat: &tgapi.Chat{ID: 100, Type: tgapi.ChatTypePrivate}},
+		FromID:       42,
+		sceneRuntime: bot,
+	}
+	if err := enterCtx.EnterScene("signup"); err != nil {
+		t.Fatalf("EnterScene returned error: %v", err)
+	}
+
+	bot.handle(context.Background(), &tgapi.Update{
+		UpdateID: 23,
+		Type:     tgapi.UpdateTypeMessage,
+		Message: &tgapi.Message{
+			MessageID: 10,
+			Text:      "hello there",
+			Chat:      &tgapi.Chat{ID: 100, Type: tgapi.ChatTypePrivate},
+			From:      &tgapi.User{ID: 42},
+		},
+	})
+
+	if len(observer.started) != 1 {
+		t.Fatalf("expected one scene started event, got %d", len(observer.started))
+	}
+	if got := observer.started[0]; got.HandlerKind != HandlerSceneStepKind || got.HandlerName != "start" || got.Plugin != "wizard" {
+		t.Fatalf("unexpected scene step started event: %#v", got)
+	}
+	if len(observer.finished) != 1 {
+		t.Fatalf("expected one scene finished event, got %d", len(observer.finished))
+	}
+	if got := observer.finished[0]; got.HandlerKind != HandlerSceneStepKind || got.HandlerName != "start" || got.Plugin != "wizard" || got.Err != nil {
+		t.Fatalf("unexpected scene step finished event: %#v", got)
+	}
+}
+
+func TestSceneMessageObserverEmitsLifecycleEvents(t *testing.T) {
+	observer := &recordingObserver{}
+	plugin := NewPlugin[NoData]("wizard")
+	scene := plugin.Scene("signup").
+		SetEntry("start").
+		OnStep("start", func(ctx *SceneContext, db NoData) (SceneResult, error) {
+			return ctx.Stay(), nil
+		}).
+		OnMessage(func(ctx *SceneContext, db NoData) (SceneResult, error) {
+			return ctx.Exit(), nil
+		})
+
+	bot := &Bot[NoData]{
+		logger:             sneklog.NewLogger(),
+		prefixes:           []string{"/"},
+		sessionStore:       NewMemorySessionStore(),
+		sceneScopePriority: []SceneScope{SceneScopeUserChat, SceneScopeChat, SceneScopeUser},
+		observer:           observer,
+	}
+	bot.AddPlugins(plugin)
+
+	key, ok := buildSceneKey(SceneScopeUserChat, &MessageContext{
+		Msg:    &tgapi.Message{Chat: &tgapi.Chat{ID: 100, Type: tgapi.ChatTypePrivate}},
+		FromID: 42,
+	})
+	if !ok {
+		t.Fatal("expected scene key to be built")
+	}
+	if err := bot.sessionStore.Set(key, SceneSession{Scene: scene.name}); err != nil {
+		t.Fatalf("failed to seed scene session: %v", err)
+	}
+
+	bot.handle(context.Background(), &tgapi.Update{
+		UpdateID: 24,
+		Type:     tgapi.UpdateTypeMessage,
+		Message: &tgapi.Message{
+			MessageID: 11,
+			Text:      "hello there",
+			Chat:      &tgapi.Chat{ID: 100, Type: tgapi.ChatTypePrivate},
+			From:      &tgapi.User{ID: 42},
+		},
+	})
+
+	if len(observer.started) != 1 {
+		t.Fatalf("expected one scene started event, got %d", len(observer.started))
+	}
+	if got := observer.started[0]; got.HandlerKind != HandlerSceneMessageKind || got.HandlerName != "message_fallback" || got.Plugin != "wizard" {
+		t.Fatalf("unexpected scene message started event: %#v", got)
+	}
+	if len(observer.finished) != 1 {
+		t.Fatalf("expected one scene finished event, got %d", len(observer.finished))
+	}
+	if got := observer.finished[0]; got.HandlerKind != HandlerSceneMessageKind || got.HandlerName != "message_fallback" || got.Plugin != "wizard" || got.Err != nil {
+		t.Fatalf("unexpected scene message finished event: %#v", got)
+	}
+}
+
+func TestScenePayloadHandlerRunsBeforeStep(t *testing.T) {
+	payloadCalled := false
+	stepCalled := false
+
+	plugin := NewPlugin[NoData]("wizard")
+	plugin.Scene("signup").
+		SetEntry("start").
+		OnStep("start", func(ctx *SceneContext, db NoData) (SceneResult, error) {
+			stepCalled = true
+			return ctx.Stay(), nil
+		}).
+		OnPayload("confirm", func(ctx *SceneContext, db NoData) (SceneResult, error) {
+			payloadCalled = true
+			if got, want := ctx.Args, []string{"7", "ok"}; len(got) != len(want) || got[0] != want[0] || got[1] != want[1] {
+				t.Fatalf("unexpected payload args: got %v want %v", got, want)
+			}
+			if ctx.Text != "" {
+				t.Fatalf("callback flow must not populate Text, got %q", ctx.Text)
+			}
+			return ctx.Exit(), nil
+		})
+
+	bot := &Bot[NoData]{
+		logger:             sneklog.NewLogger(),
+		payloadType:        BotPayloadJSON,
+		sessionStore:       NewMemorySessionStore(),
+		sceneScopePriority: []SceneScope{SceneScopeUserChat, SceneScopeChat, SceneScopeUser},
+	}
+	bot.AddPlugins(plugin)
+
+	enterCtx := &MessageContext{
+		Msg:          &tgapi.Message{Chat: &tgapi.Chat{ID: 100, Type: tgapi.ChatTypePrivate}},
+		FromID:       42,
+		sceneRuntime: bot,
+	}
+	if err := enterCtx.EnterScene("signup"); err != nil {
+		t.Fatalf("EnterScene returned error: %v", err)
+	}
+
+	data, err := encodeJSONPayload(CallbackData{Command: "confirm", Args: []string{"7", "ok"}})
+	if err != nil {
+		t.Fatalf("encodeJSONPayload returned error: %v", err)
+	}
+
+	bot.handle(context.Background(), &tgapi.Update{
+		UpdateID: 25,
+		Type:     tgapi.UpdateTypeCallbackQuery,
+		CallbackQuery: &tgapi.CallbackQuery{
+			ID:   "cb-scene",
+			Data: data,
+			From: tgapi.User{ID: 42},
+			Message: &tgapi.Message{
+				MessageID: 12,
+				Chat:      &tgapi.Chat{ID: 100, Type: tgapi.ChatTypePrivate},
+			},
+		},
+	})
+
+	if !payloadCalled {
+		t.Fatal("expected scene payload handler to be called")
+	}
+	if stepCalled {
+		t.Fatal("expected scene payload to short-circuit the active step")
+	}
+}
+
+func TestScenePayloadObserverEmitsLifecycleEvents(t *testing.T) {
+	observer := &recordingObserver{}
+	plugin := NewPlugin[NoData]("wizard")
+	plugin.Scene("signup").
+		SetEntry("start").
+		OnStep("start", func(ctx *SceneContext, db NoData) (SceneResult, error) {
+			return ctx.Stay(), nil
+		}).
+		OnPayload("confirm", func(ctx *SceneContext, db NoData) (SceneResult, error) {
+			return ctx.Exit(), nil
+		})
+
+	bot := &Bot[NoData]{
+		logger:             sneklog.NewLogger(),
+		payloadType:        BotPayloadJSON,
+		sessionStore:       NewMemorySessionStore(),
+		sceneScopePriority: []SceneScope{SceneScopeUserChat, SceneScopeChat, SceneScopeUser},
+		observer:           observer,
+	}
+	bot.AddPlugins(plugin)
+
+	enterCtx := &MessageContext{
+		Msg:          &tgapi.Message{Chat: &tgapi.Chat{ID: 100, Type: tgapi.ChatTypePrivate}},
+		FromID:       42,
+		sceneRuntime: bot,
+	}
+	if err := enterCtx.EnterScene("signup"); err != nil {
+		t.Fatalf("EnterScene returned error: %v", err)
+	}
+
+	data, err := encodeJSONPayload(CallbackData{Command: "confirm"})
+	if err != nil {
+		t.Fatalf("encodeJSONPayload returned error: %v", err)
+	}
+
+	bot.handle(context.Background(), &tgapi.Update{
+		UpdateID: 26,
+		Type:     tgapi.UpdateTypeCallbackQuery,
+		CallbackQuery: &tgapi.CallbackQuery{
+			ID:   "cb-scene",
+			Data: data,
+			From: tgapi.User{ID: 42},
+			Message: &tgapi.Message{
+				MessageID: 13,
+				Chat:      &tgapi.Chat{ID: 100, Type: tgapi.ChatTypePrivate},
+			},
+		},
+	})
+
+	if len(observer.started) != 1 {
+		t.Fatalf("expected one scene started event, got %d", len(observer.started))
+	}
+	if got := observer.started[0]; got.HandlerKind != HandlerScenePayloadKind || got.HandlerName != "confirm" || got.Plugin != "wizard" {
+		t.Fatalf("unexpected scene payload started event: %#v", got)
+	}
+	if len(observer.finished) != 1 {
+		t.Fatalf("expected one scene finished event, got %d", len(observer.finished))
+	}
+	if got := observer.finished[0]; got.HandlerKind != HandlerScenePayloadKind || got.HandlerName != "confirm" || got.Plugin != "wizard" || got.Err != nil {
+		t.Fatalf("unexpected scene payload finished event: %#v", got)
+	}
+}
+
+func TestSceneUnmatchedPayloadFallsThroughWithoutRunningStep(t *testing.T) {
+	stepCalled := false
+
+	plugin := NewPlugin[NoData]("wizard")
+	plugin.Payload("ping", func(ctx *MessageContext, db NoData) error { return nil })
+	plugin.Scene("signup").
+		SetEntry("start").
+		OnStep("start", func(ctx *SceneContext, db NoData) (SceneResult, error) {
+			stepCalled = true
+			return ctx.Stay(), nil
+		})
+
+	bot := &Bot[NoData]{
+		logger:             sneklog.NewLogger(),
+		payloadType:        BotPayloadJSON,
+		sessionStore:       NewMemorySessionStore(),
+		sceneScopePriority: []SceneScope{SceneScopeUserChat, SceneScopeChat, SceneScopeUser},
+	}
+	bot.AddPlugins(plugin)
+
+	enterCtx := &MessageContext{
+		Msg:          &tgapi.Message{Chat: &tgapi.Chat{ID: 100, Type: tgapi.ChatTypePrivate}},
+		FromID:       42,
+		sceneRuntime: bot,
+	}
+	if err := enterCtx.EnterScene("signup"); err != nil {
+		t.Fatalf("EnterScene returned error: %v", err)
+	}
+
+	key, ok := buildSceneKey(SceneScopeUserChat, &MessageContext{
+		Msg:    &tgapi.Message{Chat: &tgapi.Chat{ID: 100, Type: tgapi.ChatTypePrivate}},
+		FromID: 42,
+	})
+	if !ok {
+		t.Fatal("expected scene key to be built")
+	}
+
+	data, err := encodeJSONPayload(CallbackData{Command: "ping"})
+	if err != nil {
+		t.Fatalf("encodeJSONPayload returned error: %v", err)
+	}
+
+	bot.handle(context.Background(), &tgapi.Update{
+		UpdateID: 27,
+		Type:     tgapi.UpdateTypeCallbackQuery,
+		CallbackQuery: &tgapi.CallbackQuery{
+			ID:   "cb-global",
+			Data: data,
+			From: tgapi.User{ID: 42},
+			Message: &tgapi.Message{
+				MessageID: 14,
+				Chat:      &tgapi.Chat{ID: 100, Type: tgapi.ChatTypePrivate},
+			},
+		},
+	})
+
+	if stepCalled {
+		t.Fatal("scene step must not run for an unmatched payload")
+	}
+
+	after, err := bot.sessionStore.Get(key)
+	if err != nil {
+		t.Fatalf("Get after handle returned error: %v", err)
+	}
+	if after.Scene != "signup" || after.Step != "start" {
+		t.Fatalf("unexpected session after payload fallback: %#v", after)
+	}
+}
+
+func TestScenePassDoesNotPersistSessionData(t *testing.T) {
+	commandCalled := false
+
+	plugin := NewPlugin[NoData]("wizard")
+	plugin.Command("ping", func(ctx *MessageContext, db NoData) error {
+		commandCalled = true
+		return nil
+	})
+	plugin.Scene("signup").
+		SetEntry("start").
+		OnStep("start", func(ctx *SceneContext, db NoData) (SceneResult, error) {
+			if err := ctx.SaveData(struct {
+				Value string `json:"value"`
+			}{Value: "changed"}); err != nil {
+				t.Fatalf("SaveData returned error: %v", err)
+			}
+			return ctx.Pass(), nil
+		})
+
+	bot := &Bot[NoData]{
+		logger:             sneklog.NewLogger(),
+		prefixes:           []string{"/"},
+		sessionStore:       NewMemorySessionStore(),
+		sceneScopePriority: []SceneScope{SceneScopeUserChat, SceneScopeChat, SceneScopeUser},
+	}
+	bot.AddPlugins(plugin)
+
+	enterCtx := &MessageContext{
+		Msg:          &tgapi.Message{Chat: &tgapi.Chat{ID: 100, Type: tgapi.ChatTypePrivate}},
+		FromID:       42,
+		sceneRuntime: bot,
+	}
+	if err := enterCtx.EnterScene("signup"); err != nil {
+		t.Fatalf("EnterScene returned error: %v", err)
+	}
+
+	key, ok := buildSceneKey(SceneScopeUserChat, &MessageContext{
+		Msg:    &tgapi.Message{Chat: &tgapi.Chat{ID: 100, Type: tgapi.ChatTypePrivate}},
+		FromID: 42,
+	})
+	if !ok {
+		t.Fatal("expected scene key to be built")
+	}
+
+	before, err := bot.sessionStore.Get(key)
+	if err != nil {
+		t.Fatalf("Get before handle returned error: %v", err)
+	}
+	if before.HasData() {
+		t.Fatalf("expected empty session data before handle, got %#v", before)
+	}
+
+	bot.handle(context.Background(), &tgapi.Update{
+		UpdateID: 3,
+		Type:     tgapi.UpdateTypeMessage,
+		Message: &tgapi.Message{
+			MessageID: 9,
+			Text:      "/ping",
+			Chat:      &tgapi.Chat{ID: 100, Type: tgapi.ChatTypePrivate},
+			From:      &tgapi.User{ID: 42},
+		},
+	})
+
+	if !commandCalled {
+		t.Fatal("expected normal command routing to continue after SceneActionPass")
+	}
+
+	after, err := bot.sessionStore.Get(key)
+	if err != nil {
+		t.Fatalf("Get after handle returned error: %v", err)
+	}
+	if after.Scene != "signup" || after.Step != "start" {
+		t.Fatalf("unexpected session after pass: %#v", after)
+	}
+	if after.HasData() {
+		t.Fatalf("expected SceneActionPass to leave session data unchanged, got %#v", after)
+	}
+}
+
+func TestSceneUnmatchedCommandFallsThroughWithoutRunningStep(t *testing.T) {
+	commandCalled := false
+	stepCalled := false
+
+	plugin := NewPlugin[NoData]("wizard")
+	plugin.Scene("signup").
+		SetEntry("start").
+		OnStep("start", func(ctx *SceneContext, db NoData) (SceneResult, error) {
+			stepCalled = true
+			return ctx.Stay(), nil
+		})
+	plugin.Command("ping", func(ctx *MessageContext, db NoData) error {
+		commandCalled = true
+		return nil
+	})
+
+	bot := &Bot[NoData]{
+		logger:             sneklog.NewLogger(),
+		prefixes:           []string{"/"},
+		sessionStore:       NewMemorySessionStore(),
+		sceneScopePriority: []SceneScope{SceneScopeUserChat, SceneScopeChat, SceneScopeUser},
+	}
+	bot.AddPlugins(plugin)
+
+	enterCtx := &MessageContext{
+		Msg:          &tgapi.Message{Chat: &tgapi.Chat{ID: 100, Type: tgapi.ChatTypePrivate}},
+		FromID:       42,
+		sceneRuntime: bot,
+	}
+	if err := enterCtx.EnterScene("signup"); err != nil {
+		t.Fatalf("EnterScene returned error: %v", err)
+	}
+
+	key, ok := buildSceneKey(SceneScopeUserChat, &MessageContext{
+		Msg:    &tgapi.Message{Chat: &tgapi.Chat{ID: 100, Type: tgapi.ChatTypePrivate}},
+		FromID: 42,
+	})
+	if !ok {
+		t.Fatal("expected scene key to be built")
+	}
+
+	bot.handle(context.Background(), &tgapi.Update{
+		UpdateID: 5,
+		Type:     tgapi.UpdateTypeMessage,
+		Message: &tgapi.Message{
+			MessageID: 10,
+			Text:      "/ping",
+			Chat:      &tgapi.Chat{ID: 100, Type: tgapi.ChatTypePrivate},
+			From:      &tgapi.User{ID: 42},
+		},
+	})
+
+	if !commandCalled {
+		t.Fatal("expected normal command routing to handle /ping")
+	}
+	if stepCalled {
+		t.Fatal("scene step must not run for an unmatched slash-command")
+	}
+
+	after, err := bot.sessionStore.Get(key)
+	if err != nil {
+		t.Fatalf("Get after handle returned error: %v", err)
+	}
+	if after.Scene != "signup" || after.Step != "start" {
+		t.Fatalf("unexpected session after command fallback: %#v", after)
+	}
+}
+
+func TestSceneMessageFallbackRunsWhenNoCommandOrStepMatch(t *testing.T) {
+	fallbackCalled := false
+
+	plugin := NewPlugin[NoData]("wizard")
+	plugin.Scene("signup").
+		SetEntry("start").
+		OnStep("start", func(ctx *SceneContext, db NoData) (SceneResult, error) {
+			return ctx.Stay(), nil
+		}).
+		OnMessage(func(ctx *SceneContext, db NoData) (SceneResult, error) {
+			fallbackCalled = true
+			if ctx.Text != "hello fallback" {
+				t.Fatalf("unexpected fallback text: got %q want %q", ctx.Text, "hello fallback")
+			}
+			return ctx.Exit(), nil
+		})
+
+	bot := &Bot[NoData]{
+		logger:             sneklog.NewLogger(),
+		prefixes:           []string{"/"},
+		sessionStore:       NewMemorySessionStore(),
+		sceneScopePriority: []SceneScope{SceneScopeUserChat, SceneScopeChat, SceneScopeUser},
+	}
+	bot.AddPlugins(plugin)
+
+	enterCtx := &MessageContext{
+		Msg:          &tgapi.Message{Chat: &tgapi.Chat{ID: 100, Type: tgapi.ChatTypePrivate}},
+		FromID:       42,
+		sceneRuntime: bot,
+	}
+	if err := enterCtx.EnterScene("signup"); err != nil {
+		t.Fatalf("EnterScene returned error: %v", err)
+	}
+
+	key, ok := buildSceneKey(SceneScopeUserChat, &MessageContext{
+		Msg:    &tgapi.Message{Chat: &tgapi.Chat{ID: 100, Type: tgapi.ChatTypePrivate}},
+		FromID: 42,
+	})
+	if !ok {
+		t.Fatal("expected scene key to be built")
+	}
+	if err := bot.sessionStore.Set(key, SceneSession{Scene: "signup", Step: "unknown"}); err != nil {
+		t.Fatalf("Set returned error: %v", err)
+	}
+
+	bot.handle(context.Background(), &tgapi.Update{
+		UpdateID: 4,
+		Type:     tgapi.UpdateTypeMessage,
+		Message: &tgapi.Message{
+			MessageID: 10,
+			Text:      "hello fallback",
+			Chat:      &tgapi.Chat{ID: 100, Type: tgapi.ChatTypePrivate},
+			From:      &tgapi.User{ID: 42},
+		},
+	})
+
+	if !fallbackCalled {
+		t.Fatal("expected scene fallback handler to be called")
+	}
+}
+
+func TestFindSceneSessionSupportsUserScopeWithoutMessage(t *testing.T) {
+	bot := &Bot[NoData]{
+		logger:             sneklog.NewLogger(),
+		sessionStore:       NewMemorySessionStore(),
+		sceneScopePriority: []SceneScope{SceneScopeUser, SceneScopeChat, SceneScopeUserChat},
+	}
+
+	if err := bot.sessionStore.Set("user_id:42", SceneSession{Scene: "signup", Step: "start"}); err != nil {
+		t.Fatalf("Set returned error: %v", err)
+	}
+
+	key, session, err := bot.findSceneSession(&MessageContext{FromID: 42})
+	if err != nil {
+		t.Fatalf("findSceneSession returned error: %v", err)
+	}
+	if key != "user_id:42" {
+		t.Fatalf("unexpected session key: got %q want %q", key, "user_id:42")
+	}
+	if session.Scene != "signup" || session.Step != "start" {
+		t.Fatalf("unexpected session: %#v", session)
+	}
+}
+
+func TestSceneStoreErrorsPropagate(t *testing.T) {
+	getErr := errors.New("get failed")
+	setErr := errors.New("set failed")
+
+	t.Run("find scene session get error", func(t *testing.T) {
+		bot := &Bot[NoData]{
+			logger:             sneklog.NewLogger(),
+			sessionStore:       failingSessionStore{getErr: getErr},
+			sceneScopePriority: []SceneScope{SceneScopeUser},
+		}
+
+		_, _, err := bot.findSceneSession(&MessageContext{FromID: 42})
+		if !errors.Is(err, getErr) {
+			t.Fatalf("expected getErr, got %v", err)
+		}
+	})
+
+	t.Run("apply scene result set error", func(t *testing.T) {
+		scene := NewScene[NoData]("signup").OnStep("start", func(ctx *SceneContext, db NoData) (SceneResult, error) {
+			return ctx.Stay(), nil
+		})
+		bot := &Bot[NoData]{
+			logger:             sneklog.NewLogger(),
+			sessionStore:       failingSessionStore{setErr: setErr},
+			sceneScopePriority: []SceneScope{SceneScopeUserChat, SceneScopeChat, SceneScopeUser},
+		}
+
+		_, err := bot.applySceneResult(scene, &SceneContext{
+			MessageContext: &MessageContext{},
+			sess:           SceneSession{Scene: "signup", Step: "start"},
+			key:            "user_id:42:chat_id:100",
+		}, SceneResult{Action: SceneActionStay})
+		if !errors.Is(err, setErr) {
+			t.Fatalf("expected setErr, got %v", err)
+		}
+	})
+}

split.go

@@ -0,0 +1,44 @@
+package laniakea
+
+// SplitMessageText splits plain text into Telegram-safe message chunks.
+//
+// The function preserves the original text exactly: concatenating all returned
+// chunks reconstructs text byte-for-byte. It prefers splitting at newlines or
+// spaces within the Telegram message limit and falls back to hard rune-based
+// splits when no separator is available.
+func SplitMessageText(text string) []string {
+	return splitTextByLimit(text, maxMessageTextLen)
+}
+
+func splitTextByLimit(text string, limit int) []string {
+	if text == "" {
+		return nil
+	}
+
+	runes := []rune(text)
+	chunks := make([]string, 0, len(runes)/limit+1)
+
+	for start := 0; start < len(runes); {
+		end := start + limit
+		if end >= len(runes) {
+			chunks = append(chunks, string(runes[start:]))
+			break
+		}
+
+		splitAt := -1
+		for i := end - 1; i > start; i-- {
+			if runes[i] == '\n' || runes[i] == ' ' {
+				splitAt = i + 1
+				break
+			}
+		}
+		if splitAt == -1 {
+			splitAt = end
+		}
+
+		chunks = append(chunks, string(runes[start:splitAt]))
+		start = splitAt
+	}
+
+	return chunks
+}

tgapi/api.go

@@ -9,8 +9,8 @@ import (
 	"net/http"
 	"time"
 
-	"git.nix13.pw/scuroneko/laniakea/utils"
+	"git.scuroneko.dev/scuroneko/laniakea/utils"
-	"git.nix13.pw/scuroneko/slog"
+	"git.scuroneko.dev/scuroneko/sneklog/v2"
 )
 
 // APIOpts holds configuration options for initializing the Telegram API client.
@@ -19,7 +19,10 @@ type APIOpts struct {
 	token         string
 	client        *http.Client
 	useTestServer bool
-	apiUrl        string
+	apiURL        string
+
+	logFormat    utils.LogFormat
+	logFormatter *sneklog.Formatter
 
 	limiter           *utils.RateLimiter
 	dropOverflowLimit bool
@@ -32,7 +35,7 @@ func NewAPIOpts(token string) *APIOpts {
 		token:         token,
 		client:        nil,
 		useTestServer: false,
-		apiUrl:        "https://api.telegram.org",
+		apiURL:        "https://api.telegram.org",
 	}
 }
 
@@ -52,15 +55,27 @@ func (opts *APIOpts) UseTestServer(use bool) *APIOpts {
 	return opts
 }
 
-// SetAPIUrl overrides the default Telegram API URL.
+// SetAPIURL overrides the default Telegram API URL.
 // Useful for self-hosted bots or proxies.
-func (opts *APIOpts) SetAPIUrl(apiUrl string) *APIOpts {
+func (opts *APIOpts) SetAPIURL(apiURL string) *APIOpts {
-	if apiUrl != "" {
+	if apiURL != "" {
-		opts.apiUrl = apiUrl
+		opts.apiURL = apiURL
 	}
 	return opts
 }
 
+// SetLogFormat sets the output format used by API-managed loggers.
+func (opts *APIOpts) SetLogFormat(format utils.LogFormat) *APIOpts {
+	opts.logFormat = format
+	return opts
+}
+
+// SetLogFormatter sets the formatter used by API-managed logger writers.
+func (opts *APIOpts) SetLogFormatter(formatter *sneklog.Formatter) *APIOpts {
+	opts.logFormatter = formatter
+	return opts
+}
+
 // 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 {
@@ -68,10 +83,10 @@ func (opts *APIOpts) SetLimiter(limiter *utils.RateLimiter) *APIOpts {
 	return opts
 }
 
-// SetLimiterDrop enables "drop mode" for rate limiting.
+// SetDropRateLimitOverflow 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 {
+func (opts *APIOpts) SetDropRateLimitOverflow(b bool) *APIOpts {
 	opts.dropOverflowLimit = b
 	return opts
 }
@@ -85,9 +100,12 @@ func (opts *APIOpts) SetLimiterDrop(b bool) *APIOpts {
 type API struct {
 	token         string
 	client        *http.Client
-	logger        *slog.Logger
+	logger        *sneklog.Logger
 	useTestServer bool
-	apiUrl        string
+	apiURL        string
+
+	logFormat    utils.LogFormat
+	logFormatter *sneklog.Formatter
 
 	pool              *workerPool
 	Limiter           *utils.RateLimiter
@@ -97,7 +115,14 @@ type API struct {
 // NewAPI creates a new API client from options.
 // Always call Close() when done to release resources.
 func NewAPI(opts *APIOpts) *API {
-	l := utils.CreateLogger("API", utils.GetLoggerLevel())
+	if opts == nil {
+		return nil
+	}
+	logger := utils.CreateLogger(
+		"API", utils.GetLoggerLevel(),
+		opts.logFormat, opts.logFormatter,
+	)
+	logger.AddReplacer(opts.token, "<TOKEN>")
 
 	client := opts.client
 	if client == nil {
@@ -108,11 +133,15 @@ func NewAPI(opts *APIOpts) *API {
 	pool.start()
 
 	return &API{
-		token:             opts.token,
+		token:         opts.token,
-		client:            client,
+		client:        client,
-		logger:            l,
+		logger:        logger,
-		useTestServer:     opts.useTestServer,
+		useTestServer: opts.useTestServer,
-		apiUrl:            opts.apiUrl,
+		apiURL:        opts.apiURL,
+
+		logFormat:    opts.logFormat,
+		logFormatter: opts.logFormatter,
+
 		pool:              pool,
 		Limiter:           opts.limiter,
 		dropOverflowLimit: opts.dropOverflowLimit,
@@ -132,7 +161,7 @@ func (api *API) Close() error {
 
 // GetLogger returns the internal logger for custom logging.
 // See https://core.telegram.org/bots/api
-func (api *API) GetLogger() *slog.Logger {
+func (api *API) GetLogger() *sneklog.Logger {
 	return api.logger
 }
 
@@ -142,9 +171,9 @@ type ResponseParameters struct {
 	RetryAfter      *int   `json:"retry_after,omitempty"`
 }
 
-// ApiResponse is the standard Telegram Bot API response structure.
+// TelegramResponse is the standard Telegram Bot API response structure.
 // Generic over Result type R.
-type ApiResponse[R any] struct {
+type TelegramResponse[R any] struct {
 	Ok          bool                `json:"ok"`
 	Description string              `json:"description,omitempty"`
 	Result      R                   `json:"result,omitempty"`
@@ -161,7 +190,7 @@ type ApiResponse[R any] struct {
 type TelegramRequest[R, P any] struct {
 	method string
 	params P
-	chatId int64
+	chatID int64
 }
 
 // NewRequest creates a low-level TelegramRequest with no associated chat ID.
@@ -171,8 +200,8 @@ func NewRequest[R, P any](method string, params P) TelegramRequest[R, P] {
 
 // NewRequestWithChatID creates a low-level TelegramRequest with an associated chat ID.
 // The chat ID is used for per-chat rate limiting.
-func NewRequestWithChatID[R, P any](method string, params P, chatId int64) TelegramRequest[R, P] {
+func NewRequestWithChatID[R, P any](method string, params P, chatID int64) TelegramRequest[R, P] {
-	return TelegramRequest[R, P]{method, params, chatId}
+	return TelegramRequest[R, P]{method, params, chatID}
 }
 
 func (r TelegramRequest[R, P]) doRequest(ctx context.Context, api *API) (R, error) {
@@ -186,8 +215,7 @@ func (r TelegramRequest[R, P]) doRequest(ctx context.Context, api *API) (R, erro
 	if api.useTestServer {
 		methodPrefix = "/test"
 	}
-	url := fmt.Sprintf("%s/bot%s%s/%s", api.apiUrl, api.token, methodPrefix, r.method)
+	url := fmt.Sprintf("%s/bot%s%s/%s", api.apiURL, api.token, methodPrefix, r.method)
-
 	req, err := http.NewRequestWithContext(ctx, "POST", url, nil)
 	if err != nil {
 		return zero, fmt.Errorf("failed to create request: %w", err)
@@ -200,7 +228,7 @@ func (r TelegramRequest[R, P]) doRequest(ctx context.Context, api *API) (R, erro
 	for {
 		// Apply rate limiting before making the request
 		if api.Limiter != nil {
-			if err := api.Limiter.Check(ctx, api.dropOverflowLimit, r.chatId); err != nil {
+			if err := api.Limiter.Check(ctx, api.dropOverflowLimit, r.chatID); err != nil {
 				return zero, err
 			}
 		}
@@ -228,20 +256,30 @@ func (r TelegramRequest[R, P]) doRequest(ctx context.Context, api *API) (R, erro
 		}
 
 		if !response.Ok {
+			responseErr := &ResponseError{
+				Code:        response.ErrorCode,
+				Description: response.Description,
+				Parameters:  response.Parameters,
+			}
+
 			// 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)
+				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 api.Limiter != nil {
-					if r.chatId > 0 {
+					if r.chatID > 0 {
-						api.Limiter.SetChatLock(r.chatId, after)
+						api.Limiter.SetChatLock(r.chatID, after)
 					} else {
 						api.Limiter.SetGlobalLock(after)
 					}
 				}
 
+				if r.method == "getUpdates" {
+					return zero, responseErr
+				}
+
 				// Wait and retry
 				select {
 				case <-ctx.Done():
@@ -252,7 +290,7 @@ func (r TelegramRequest[R, P]) doRequest(ctx context.Context, api *API) (R, erro
 			}
 
 			// Other API errors
-			return zero, fmt.Errorf("[%d] %s", response.ErrorCode, response.Description)
+			return zero, responseErr
 		}
 
 		return response.Result, nil
@@ -291,15 +329,13 @@ func (r TelegramRequest[R, P]) Do(api *API) (R, error) {
 	return r.DoWithContext(context.Background(), api)
 }
 
-// Internal helper that reads and caps a Telegram response body.
 func readBody(body io.ReadCloser) ([]byte, error) {
 	reader := io.LimitReader(body, 10<<20) // 10 MB
 	return io.ReadAll(reader)
 }
 
-// Internal helper that parses a typed Telegram API response body.
+func parseBody[R any](data []byte) (TelegramResponse[R], error) {
-func parseBody[R any](data []byte) (ApiResponse[R], error) {
+	var resp TelegramResponse[R]
-	var resp ApiResponse[R]
 	err := json.Unmarshal(data, &resp)
 	if err != nil {
 		return resp, fmt.Errorf("failed to unmarshal JSON: %w", err)

tgapi/api_test.go

@@ -40,7 +40,7 @@ func TestAPILeavesAcceptEncodingToHTTPTransport(t *testing.T) {
 
 	api := NewAPI(
 		NewAPIOpts("token").
-			SetAPIUrl("https://example.test").
+			SetAPIURL("https://example.test").
 			SetHTTPClient(client),
 	)
 	defer func() {
@@ -77,7 +77,7 @@ func TestAPICloseClosesIdleConnections(t *testing.T) {
 
 	api := NewAPI(
 		NewAPIOpts("token").
-			SetAPIUrl("https://example.test").
+			SetAPIURL("https://example.test").
 			SetHTTPClient(&http.Client{Transport: transport}),
 	)
 

tgapi/attachments_methods.go

@@ -2,9 +2,10 @@ package tgapi
 
 import "context"
 
-// SendPhotoP holds parameters for the sendPhoto method.
+// SendPhoto holds parameters for the sendPhoto method.
+// Since: Bot API 1.0
 // See https://core.telegram.org/bots/api#sendphoto
-type SendPhotoP struct {
+type SendPhoto struct {
 	BusinessConnectionID  string `json:"business_connection_id,omitempty"`
 	ChatID                int64  `json:"chat_id"`
 	MessageThreadID       int    `json:"message_thread_id,omitempty"`
@@ -28,23 +29,26 @@ type SendPhotoP struct {
 }
 
 // SendPhoto sends a photo.
+// Since: Bot API 1.0
 // See https://core.telegram.org/bots/api#sendphoto
-func (api *API) SendPhoto(params SendPhotoP) (Message, error) {
+func (api *API) SendPhoto(params SendPhoto) (Message, error) {
 	req := NewRequestWithChatID[Message]("sendPhoto", params, params.ChatID)
 	return req.Do(api)
 }
 
 // SendPhotoWithContext is the context-aware variant of SendPhoto.
+// Since: Bot API 1.0
 // It executes the same request but uses ctx for cancellation and deadlines.
 // See https://core.telegram.org/bots/api#sendphoto
-func (api *API) SendPhotoWithContext(ctx context.Context, params SendPhotoP) (Message, error) {
+func (api *API) SendPhotoWithContext(ctx context.Context, params SendPhoto) (Message, error) {
 	req := NewRequestWithChatID[Message]("sendPhoto", params, params.ChatID)
 	return req.DoWithContext(ctx, api)
 }
 
-// SendAudioP holds parameters for the sendAudio method.
+// SendAudio holds parameters for the sendAudio method.
+// Since: Bot API 1.2
 // See https://core.telegram.org/bots/api#sendaudio
-type SendAudioP struct {
+type SendAudio struct {
 	BusinessConnectionID  string `json:"business_connection_id,omitempty"`
 	ChatID                int64  `json:"chat_id"`
 	MessageThreadID       int    `json:"message_thread_id,omitempty"`
@@ -70,23 +74,26 @@ type SendAudioP struct {
 }
 
 // SendAudio sends an audio file.
+// Since: Bot API 1.2
 // See https://core.telegram.org/bots/api#sendaudio
-func (api *API) SendAudio(params SendAudioP) (Message, error) {
+func (api *API) SendAudio(params SendAudio) (Message, error) {
 	req := NewRequestWithChatID[Message]("sendAudio", params, params.ChatID)
 	return req.Do(api)
 }
 
 // SendAudioWithContext is the context-aware variant of SendAudio.
+// Since: Bot API 1.2
 // It executes the same request but uses ctx for cancellation and deadlines.
 // See https://core.telegram.org/bots/api#sendaudio
-func (api *API) SendAudioWithContext(ctx context.Context, params SendAudioP) (Message, error) {
+func (api *API) SendAudioWithContext(ctx context.Context, params SendAudio) (Message, error) {
 	req := NewRequestWithChatID[Message]("sendAudio", params, params.ChatID)
 	return req.DoWithContext(ctx, api)
 }
 
-// SendDocumentP holds parameters for the sendDocument method.
+// SendDocument holds parameters for the sendDocument method.
+// Since: Bot API 1.0
 // See https://core.telegram.org/bots/api#senddocument
-type SendDocumentP struct {
+type SendDocument struct {
 	BusinessConnectionID  string `json:"business_connection_id,omitempty"`
 	ChatID                int64  `json:"chat_id"`
 	MessageThreadID       int    `json:"message_thread_id,omitempty"`
@@ -110,23 +117,26 @@ type SendDocumentP struct {
 }
 
 // SendDocument sends a document.
+// Since: Bot API 1.0
 // See https://core.telegram.org/bots/api#senddocument
-func (api *API) SendDocument(params SendDocumentP) (Message, error) {
+func (api *API) SendDocument(params SendDocument) (Message, error) {
 	req := NewRequestWithChatID[Message]("sendDocument", params, params.ChatID)
 	return req.Do(api)
 }
 
 // SendDocumentWithContext is the context-aware variant of SendDocument.
+// Since: Bot API 1.0
 // It executes the same request but uses ctx for cancellation and deadlines.
 // See https://core.telegram.org/bots/api#senddocument
-func (api *API) SendDocumentWithContext(ctx context.Context, params SendDocumentP) (Message, error) {
+func (api *API) SendDocumentWithContext(ctx context.Context, params SendDocument) (Message, error) {
 	req := NewRequestWithChatID[Message]("sendDocument", params, params.ChatID)
 	return req.DoWithContext(ctx, api)
 }
 
-// SendVideoP holds parameters for the sendVideo method.
+// SendVideo holds parameters for the sendVideo method.
+// Since: Bot API 1.0
 // See https://core.telegram.org/bots/api#sendvideo
-type SendVideoP struct {
+type SendVideo struct {
 	BusinessConnectionID  string `json:"business_connection_id,omitempty"`
 	ChatID                int64  `json:"chat_id"`
 	MessageThreadID       int    `json:"message_thread_id,omitempty"`
@@ -158,23 +168,26 @@ type SendVideoP struct {
 }
 
 // SendVideo sends a video.
+// Since: Bot API 1.0
 // See https://core.telegram.org/bots/api#sendvideo
-func (api *API) SendVideo(params SendVideoP) (Message, error) {
+func (api *API) SendVideo(params SendVideo) (Message, error) {
 	req := NewRequestWithChatID[Message]("sendVideo", params, params.ChatID)
 	return req.Do(api)
 }
 
 // SendVideoWithContext is the context-aware variant of SendVideo.
+// Since: Bot API 1.0
 // It executes the same request but uses ctx for cancellation and deadlines.
 // See https://core.telegram.org/bots/api#sendvideo
-func (api *API) SendVideoWithContext(ctx context.Context, params SendVideoP) (Message, error) {
+func (api *API) SendVideoWithContext(ctx context.Context, params SendVideo) (Message, error) {
 	req := NewRequestWithChatID[Message]("sendVideo", params, params.ChatID)
 	return req.DoWithContext(ctx, api)
 }
 
-// SendAnimationP holds parameters for the sendAnimation method.
+// SendAnimation holds parameters for the sendAnimation method.
+// Since: Bot API 4.0
 // See https://core.telegram.org/bots/api#sendanimation
-type SendAnimationP struct {
+type SendAnimation struct {
 	BusinessConnectionID  string `json:"business_connection_id,omitempty"`
 	ChatID                int64  `json:"chat_id"`
 	MessageThreadID       int    `json:"message_thread_id,omitempty"`
@@ -202,23 +215,26 @@ type SendAnimationP struct {
 }
 
 // SendAnimation sends an animation file (GIF or H.264/MPEG-4 AVC video without sound).
+// Since: Bot API 4.0
 // See https://core.telegram.org/bots/api#sendanimation
-func (api *API) SendAnimation(params SendAnimationP) (Message, error) {
+func (api *API) SendAnimation(params SendAnimation) (Message, error) {
 	req := NewRequestWithChatID[Message]("sendAnimation", params, params.ChatID)
 	return req.Do(api)
 }
 
 // SendAnimationWithContext is the context-aware variant of SendAnimation.
+// Since: Bot API 4.0
 // It executes the same request but uses ctx for cancellation and deadlines.
 // See https://core.telegram.org/bots/api#sendanimation
-func (api *API) SendAnimationWithContext(ctx context.Context, params SendAnimationP) (Message, error) {
+func (api *API) SendAnimationWithContext(ctx context.Context, params SendAnimation) (Message, error) {
 	req := NewRequestWithChatID[Message]("sendAnimation", params, params.ChatID)
 	return req.DoWithContext(ctx, api)
 }
 
-// SendVoiceP holds parameters for the sendVoice method.
+// SendVoice holds parameters for the sendVoice method.
+// Since: Bot API 1.2
 // See https://core.telegram.org/bots/api#sendvoice
-type SendVoiceP struct {
+type SendVoice struct {
 	BusinessConnectionID  string `json:"business_connection_id,omitempty"`
 	ChatID                int64  `json:"chat_id"`
 	MessageThreadID       int    `json:"message_thread_id,omitempty"`
@@ -240,23 +256,26 @@ type SendVoiceP struct {
 }
 
 // SendVoice sends a voice note.
+// Since: Bot API 1.2
 // See https://core.telegram.org/bots/api#sendvoice
-func (api *API) SendVoice(params SendVoiceP) (Message, error) {
+func (api *API) SendVoice(params SendVoice) (Message, error) {
 	req := NewRequestWithChatID[Message]("sendVoice", params, params.ChatID)
 	return req.Do(api)
 }
 
 // SendVoiceWithContext is the context-aware variant of SendVoice.
+// Since: Bot API 1.2
 // It executes the same request but uses ctx for cancellation and deadlines.
 // See https://core.telegram.org/bots/api#sendvoice
-func (api *API) SendVoiceWithContext(ctx context.Context, params SendVoiceP) (Message, error) {
+func (api *API) SendVoiceWithContext(ctx context.Context, params SendVoice) (Message, error) {
 	req := NewRequestWithChatID[Message]("sendVoice", params, params.ChatID)
 	return req.DoWithContext(ctx, api)
 }
 
-// SendVideoNoteP holds parameters for the sendVideoNote method.
+// SendVideoNote holds parameters for the sendVideoNote method.
+// Since: Bot API 3.0
 // See https://core.telegram.org/bots/api#sendvideonote
-type SendVideoNoteP struct {
+type SendVideoNote struct {
 	BusinessConnectionID  string `json:"business_connection_id,omitempty"`
 	ChatID                int64  `json:"chat_id"`
 	MessageThreadID       int    `json:"message_thread_id,omitempty"`
@@ -277,23 +296,26 @@ type SendVideoNoteP struct {
 }
 
 // SendVideoNote sends a video note (rounded video message).
+// Since: Bot API 3.0
 // See https://core.telegram.org/bots/api#sendvideonote
-func (api *API) SendVideoNote(params SendVideoNoteP) (Message, error) {
+func (api *API) SendVideoNote(params SendVideoNote) (Message, error) {
 	req := NewRequestWithChatID[Message]("sendVideoNote", params, params.ChatID)
 	return req.Do(api)
 }
 
 // SendVideoNoteWithContext is the context-aware variant of SendVideoNote.
+// Since: Bot API 3.0
 // It executes the same request but uses ctx for cancellation and deadlines.
 // See https://core.telegram.org/bots/api#sendvideonote
-func (api *API) SendVideoNoteWithContext(ctx context.Context, params SendVideoNoteP) (Message, error) {
+func (api *API) SendVideoNoteWithContext(ctx context.Context, params SendVideoNote) (Message, error) {
 	req := NewRequestWithChatID[Message]("sendVideoNote", params, params.ChatID)
 	return req.DoWithContext(ctx, api)
 }
 
-// SendPaidMediaP holds parameters for the sendPaidMedia method.
+// SendPaidMedia holds parameters for the sendPaidMedia method.
+// Since: Bot API 7.6
 // See https://core.telegram.org/bots/api#sendpaidmedia
-type SendPaidMediaP struct {
+type SendPaidMedia struct {
 	BusinessConnectionID  string `json:"business_connection_id,omitempty"`
 	ChatID                int64  `json:"chat_id"`
 	MessageThreadID       int    `json:"message_thread_id,omitempty"`
@@ -316,23 +338,26 @@ type SendPaidMediaP struct {
 }
 
 // SendPaidMedia sends paid media.
+// Since: Bot API 7.6
 // See https://core.telegram.org/bots/api#sendpaidmedia
-func (api *API) SendPaidMedia(params SendPaidMediaP) (Message, error) {
+func (api *API) SendPaidMedia(params SendPaidMedia) (Message, error) {
 	req := NewRequestWithChatID[Message]("sendPaidMedia", params, params.ChatID)
 	return req.Do(api)
 }
 
 // SendPaidMediaWithContext is the context-aware variant of SendPaidMedia.
+// Since: Bot API 7.6
 // It executes the same request but uses ctx for cancellation and deadlines.
 // See https://core.telegram.org/bots/api#sendpaidmedia
-func (api *API) SendPaidMediaWithContext(ctx context.Context, params SendPaidMediaP) (Message, error) {
+func (api *API) SendPaidMediaWithContext(ctx context.Context, params SendPaidMedia) (Message, error) {
 	req := NewRequestWithChatID[Message]("sendPaidMedia", params, params.ChatID)
 	return req.DoWithContext(ctx, api)
 }
 
-// SendMediaGroupP holds parameters for the sendMediaGroup method.
+// SendMediaGroup holds parameters for the sendMediaGroup method.
+// Since: Bot API 3.5
 // See https://core.telegram.org/bots/api#sendmediagroup
-type SendMediaGroupP struct {
+type SendMediaGroup struct {
 	BusinessConnectionID  string `json:"business_connection_id,omitempty"`
 	ChatID                int64  `json:"chat_id"`
 	MessageThreadID       int    `json:"message_thread_id,omitempty"`
@@ -347,16 +372,61 @@ type SendMediaGroupP struct {
 }
 
 // SendMediaGroup sends a group of photos, videos, documents or audios as an album.
+// Since: Bot API 3.5
 // See https://core.telegram.org/bots/api#sendmediagroup
-func (api *API) SendMediaGroup(params SendMediaGroupP) ([]Message, error) {
+func (api *API) SendMediaGroup(params SendMediaGroup) ([]Message, error) {
 	req := NewRequestWithChatID[[]Message]("sendMediaGroup", params, params.ChatID)
 	return req.Do(api)
 }
 
 // SendMediaGroupWithContext is the context-aware variant of SendMediaGroup.
+// Since: Bot API 3.5
 // It executes the same request but uses ctx for cancellation and deadlines.
 // See https://core.telegram.org/bots/api#sendmediagroup
-func (api *API) SendMediaGroupWithContext(ctx context.Context, params SendMediaGroupP) ([]Message, error) {
+func (api *API) SendMediaGroupWithContext(ctx context.Context, params SendMediaGroup) ([]Message, error) {
 	req := NewRequestWithChatID[[]Message]("sendMediaGroup", params, params.ChatID)
 	return req.DoWithContext(ctx, api)
 }
+
+// SendLivePhoto holds parameters for the sendLivePhoto method.
+// Since: Bot API 10.0
+// See https://core.telegram.org/bots/api#sendlivephoto
+type SendLivePhoto struct {
+	BusinessConnectionID  string `json:"business_connection_id,omitempty"`
+	ChatID                int64  `json:"chat_id"`
+	MessageThreadID       int    `json:"message_thread_id,omitempty"`
+	DirectMessagesTopicID int    `json:"direct_messages_topic_id,omitempty"`
+
+	LivePhoto       string          `json:"live_photo"`
+	Caption         string          `json:"caption,omitempty"`
+	ParseMode       ParseMode       `json:"parse_mode,omitempty"`
+	CaptionEntities []MessageEntity `json:"caption_entities,omitempty"`
+
+	ShowCaptionAboveMedia bool   `json:"show_caption_above_media,omitempty"`
+	HasSpoiler            bool   `json:"has_spoiler,omitempty"`
+	DisableNotification   bool   `json:"disable_notification,omitempty"`
+	ProtectContent        bool   `json:"protect_content,omitempty"`
+	AllowPaidBroadcast    bool   `json:"allow_paid_broadcast,omitempty"`
+	MessageEffectID       string `json:"message_effect_id,omitempty"`
+
+	SuggestedPostParameters *SuggestedPostParameters `json:"suggested_post_parameters,omitempty"`
+	ReplyParameters         *ReplyParameters         `json:"reply_parameters,omitempty"`
+	ReplyMarkup             *ReplyMarkup             `json:"reply_markup,omitempty"`
+}
+
+// SendLivePhoto sends a live photo.
+// Since: Bot API 10.0
+// See https://core.telegram.org/bots/api#sendlivephoto
+func (api *API) SendLivePhoto(params SendLivePhoto) (Message, error) {
+	req := NewRequestWithChatID[Message]("sendLivePhoto", params, params.ChatID)
+	return req.Do(api)
+}
+
+// SendLivePhotoWithContext is the context-aware variant of SendLivePhoto.
+// Since: Bot API 10.0
+// It executes the same request but uses ctx for cancellation and deadlines.
+// See https://core.telegram.org/bots/api#sendlivephoto
+func (api *API) SendLivePhotoWithContext(ctx context.Context, params SendLivePhoto) (Message, error) {
+	req := NewRequestWithChatID[Message]("sendLivePhoto", params, params.ChatID)
+	return req.DoWithContext(ctx, api)
+}

tgapi/attachments_types.go

@@ -1,5 +1,333 @@
 package tgapi
 
+// Animation represents an animation file (GIF or H.264/MPEG-4 AVC without sound).
+// Since: Bot API 4.0
+type Animation struct {
+	FileID       string `json:"file_id"`
+	FileUniqueID string `json:"file_unique_id"`
+	Width        int    `json:"width"`
+	Height       int    `json:"height"`
+	Duration     int    `json:"duration"`
+
+	Thumbnail *PhotoSize `json:"thumbnail,omitempty"`
+	FileName  string     `json:"file_name"`
+	MimeType  string     `json:"mime_type"`
+	FileSize  int        `json:"file_size"`
+}
+
+// Audio represents an audio file to be treated as music by the Telegram clients.
+// Since: Bot API 1.2
+// See https://core.telegram.org/bots/api#audio
+type Audio struct {
+	FileID       string `json:"file_id"`
+	FileUniqueID string `json:"file_unique_id"`
+	Duration     int    `json:"duration"`
+
+	Performer string     `json:"performer,omitempty"`
+	Title     string     `json:"title,omitempty"`
+	FileName  string     `json:"file_name,omitempty"` // Since: Bot API 5.0
+	MimeType  string     `json:"mime_type,omitempty"`
+	FileSize  int64      `json:"file_size,omitempty"`
+	Thumbnail *PhotoSize `json:"thumbnail,omitempty"`
+}
+
+// Document represents a general file (as opposed to photos, voice messages and audio files).
+// Since: Bot API 1.0
+type Document struct {
+	FileID       string     `json:"file_id"`
+	FileUniqueID string     `json:"file_unique_id"`
+	Thumbnail    *PhotoSize `json:"thumbnail,omitempty"`
+	FileName     string     `json:"file_name"`
+	MimeType     string     `json:"mime_type"`
+	FileSize     int        `json:"file_size,omitempty"`
+}
+
+// Story represents a story.
+// Since: Bot API 6.8
+type Story struct {
+	Chat Chat `json:"chat"`
+	ID   int  `json:"id"`
+}
+
+// Video represents a video file.
+// Since: Bot API 1.0
+type Video struct {
+	FileID       string `json:"file_id"`
+	FileUniqueID string `json:"file_unique_id"`
+	Width        int    `json:"width"`
+	Height       int    `json:"height"`
+	Duration     int    `json:"duration"`
+
+	Thumbnail      *PhotoSize     `json:"thumbnail,omitempty"`
+	Cover          []PhotoSize    `json:"cover,omitempty"`     // Since: Bot API 8.3
+	StartTimestamp int64          `json:"start_timestamp"`     // Since: Bot API 8.3
+	Qualities      []VideoQuality `json:"qualities,omitempty"` // Since: Bot API 9.4
+	FileName       string         `json:"file_name,omitempty"`
+	MimeType       string         `json:"mime_type,omitempty"`
+	FileSize       int64          `json:"file_size,omitempty"`
+}
+
+// VideoQuality describes an alternative quality for a video.
+// Since: Bot API 9.4
+// See https://core.telegram.org/bots/api#videoquality
+type VideoQuality struct {
+	FileID       string `json:"file_id"`
+	FileUniqueID string `json:"file_unique_id"`
+	Width        int    `json:"width"`
+	Height       int    `json:"height"`
+	Codec        string `json:"codec"`
+	FileSize     int64  `json:"file_size,omitempty"`
+}
+
+// VideoNote represents a video message.
+// Since: Bot API 3.0
+type VideoNote struct {
+	FileID       string     `json:"file_id"`
+	FileUniqueID string     `json:"file_unique_id"`
+	Length       int        `json:"length"`
+	Duration     int        `json:"duration"`
+	Thumbnail    *PhotoSize `json:"thumbnail,omitempty"`
+	FileSize     int64      `json:"file_size,omitempty"`
+}
+
+// Voice represents a voice note.
+// Since: Bot API 1.2
+type Voice struct {
+	FileID       string `json:"file_id"`
+	FileUniqueID string `json:"file_unique_id"`
+	Duration     int    `json:"duration"`
+	MimeType     string `json:"mime_type,omitempty"`
+	FileSize     int    `json:"file_size,omitempty"`
+}
+
+// PaidMediaInfo describes paid media.
+// Since: Bot API 7.6
+type PaidMediaInfo struct {
+	StarCount int         `json:"star_count"`
+	PaidMedia []PaidMedia `json:"paid_media"`
+}
+
+// PaidMediaType represents the type of paid media.
+// Since: Bot API 7.6
+type PaidMediaType string
+
+const (
+	PaidMediaPreviewType   PaidMediaType = "preview"
+	PaidMediaPhotoType     PaidMediaType = "photo"
+	PaidMediaVideoType     PaidMediaType = "video"
+	PaidMediaLivePhotoType PaidMediaType = "live_photo" // Since: Bot API 10.0
+)
+
+// PaidMedia describes paid media content.
+// Since: Bot API 7.6
+type PaidMedia struct {
+	Type PaidMediaType `json:"type,omitempty"`
+
+	Width    int `json:"width,omitempty"`
+	Height   int `json:"height,omitempty"`
+	Duration int `json:"duration,omitempty"`
+
+	Photo []PhotoSize `json:"photo,omitempty"`
+
+	Video     *Video     `json:"video,omitempty"`
+	LivePhoto *LivePhoto `json:"live_photo,omitempty"` // Since: Bot API 10.0
+}
+
+// Contact represents a phone contact.
+// Since: Bot API 1.0
+type Contact struct {
+	PhoneNumber string `json:"phone_number"`
+	FirstName   string `json:"first_name"`
+	LastName    string `json:"last_name,omitempty"`
+	UserID      int64  `json:"user_id,omitempty"`
+	Vcard       string `json:"vcard,omitempty"`
+}
+
+// Dice represents an animated emoji with a random value.
+// Since: Bot API 4.7
+type Dice struct {
+	Emoji string `json:"emoji"`
+	Value int    `json:"value"`
+}
+
+// PollOption contains information about one answer option in a poll.
+// Since: Bot API 4.2
+// See https://core.telegram.org/bots/api#polloption
+type PollOption struct {
+	PersistentID string          `json:"persistent_id"` // Since: Bot API 9.6
+	Text         string          `json:"text"`
+	TextEntities []MessageEntity `json:"text_entities"`
+	Media        *PollMedia      `json:"media,omitempty"` // Since: Bot API 10.0
+	VoterCount   int             `json:"voter_count"`
+
+	AddedByUser  *User `json:"added_by_user,omitempty"` // Since: Bot API 9.6
+	AddedByChat  *Chat `json:"added_by_chat,omitempty"` // Since: Bot API 9.6
+	AdditionDate int   `json:"addition_date,omitempty"` // Since: Bot API 9.6
+}
+
+// InputPollOptionMedia describes the media to attach to a poll option.
+// Since: Bot API 10.0
+// See https://core.telegram.org/bots/api#inputpolloptionmedia
+type InputPollOptionMedia struct {
+	Type  string `json:"type"`
+	Media string `json:"media"`
+}
+
+// InputPollOption contains information about one answer option in a poll to be sent.
+// Since: Bot API 7.3
+// See https://core.telegram.org/bots/api#inputpolloption
+type InputPollOption struct {
+	Text          string                `json:"text"`
+	TextParseMode ParseMode             `json:"text_parse_mode,omitempty"`
+	TextEntities  []MessageEntity       `json:"text_entities,omitempty"`
+	Media         *InputPollOptionMedia `json:"media,omitempty"` // Since: Bot API 10.0
+}
+
+// InputPollMedia describes the media to attach to a poll or its explanation.
+// Since: Bot API 10.0
+// See https://core.telegram.org/bots/api#inputpollmedia
+type InputPollMedia struct {
+	Type  string `json:"type"`
+	Media string `json:"media"`
+}
+
+// PollOptionAdded describes a service message about a poll option being added.
+// Since: Bot API 9.6
+type PollOptionAdded struct {
+	PollMessage        *InaccessibleMessage `json:"poll_message,omitempty"`
+	OptionPersistentID string               `json:"option_persistent_id"`
+	OptionText         string               `json:"option_text"`
+	OptionTextEntities []MessageEntity      `json:"option_text_entities,omitempty"`
+}
+
+// PollOptionDeleted describes a service message about a poll option being deleted.
+// Since: Bot API 9.6
+type PollOptionDeleted struct {
+	PollMessage        *InaccessibleMessage `json:"poll_message,omitempty"`
+	OptionPersistentID string               `json:"option_persistent_id"`
+	OptionText         string               `json:"option_text"`
+	OptionTextEntities []MessageEntity      `json:"option_text_entities,omitempty"`
+}
+
+// PollType represents the type of a poll.
+type PollType string
+
+const (
+	// PollTypeRegular identifies a regular poll.
+	PollTypeRegular PollType = "regular"
+	// PollTypeQuiz identifies a quiz poll.
+	PollTypeQuiz PollType = "quiz"
+)
+
+// PollAnswer represents an answer of a user in a poll.
+// Since: Bot API 4.6
+// See https://core.telegram.org/bots/api#pollanswer
+type PollAnswer struct {
+	PollID              string   `json:"poll_id"`
+	VoterChat           Chat     `json:"voter_chat"` // Since: Bot API 6.8
+	User                User     `json:"user"`
+	OptionIDs           []int    `json:"option_ids"`
+	OptionPersistentIDs []string `json:"option_persistent_ids"` // Since: Bot API 9.6
+}
+
+// Poll contains information about a poll.
+// Since: Bot API 4.2
+// See https://core.telegram.org/bots/api#poll
+type Poll struct {
+	ID               string          `json:"id"`
+	Question         string          `json:"question"`
+	QuestionEntities []MessageEntity `json:"question_entities"` // Since: Bot API 7.3
+	Options          []PollOption    `json:"options"`
+	TotalVoterCount  int             `json:"total_voter_count"`
+	IsClosed         bool            `json:"is_closed,omitempty"`
+	IsAnonymous      bool            `json:"is_anonymous,omitempty"`
+	Type             PollType        `json:"type"`
+
+	AllowsMultipleAnswers bool            `json:"allows_multiple_answers,omitempty"` // Since: Bot API 4.6
+	AllowsRevoting        bool            `json:"allows_revoting,omitempty"`         // Since: Bot API 9.6
+	MembersOnly           bool            `json:"members_only,omitempty"`            // Since: Bot API 10.0
+	CountryCodes          []string        `json:"country_codes,omitempty"`           // Since: Bot API 10.0
+	CorrectOptionIDs      []int           `json:"correct_option_ids,omitempty"`      // Since: Bot API 9.6
+	Explanation           string          `json:"explanation,omitempty"`             // Since: Bot API 4.8
+	ExplanationEntities   []MessageEntity `json:"explanation_entities,omitempty"`    // Since: Bot API 4.8
+	ExplanationMedia      *PollMedia      `json:"explanation_media,omitempty"`       // Since: Bot API 10.0
+	OpenPeriod            int             `json:"open_period,omitempty"`             // Since: Bot API 4.8
+	CloseDate             int             `json:"close_date,omitempty"`              // Since: Bot API 4.8
+	Description           string          `json:"description,omitempty"`             // Since: Bot API 9.6
+	DescriptionEntities   []MessageEntity `json:"description_entities,omitempty"`    // Since: Bot API 9.6
+	Media                 *PollMedia      `json:"media,omitempty"`                   // Since: Bot API 10.0
+}
+
+// PollMedia represents media attached to a poll.
+// Since: Bot API 10.0
+type PollMedia struct {
+	Animation *Animation  `json:"animation,omitempty"`
+	Audio     *Audio      `json:"audio,omitempty"`
+	Document  *Document   `json:"document,omitempty"`
+	LivePhoto *LivePhoto  `json:"live_photo,omitempty"`
+	Location  *Location   `json:"location,omitempty"`
+	Photo     []PhotoSize `json:"photo,omitempty"`
+	Sticker   *Sticker    `json:"sticker,omitempty"`
+	Venue     *Venue      `json:"venue,omitempty"`
+	Video     *Video      `json:"video,omitempty"`
+}
+
+// ChecklistTask represents a single task in a checklist.
+// Since: Bot API 9.1
+type ChecklistTask struct {
+	ID              int             `json:"id"`
+	Text            string          `json:"text"`
+	TextEntities    []MessageEntity `json:"text_entities,omitempty"`
+	CompletedByUser *User           `json:"completed_by_user,omitempty"`
+	CompletedByChat *Chat           `json:"completed_by_chat,omitempty"`
+	CompletionDate  int             `json:"completion_date,omitempty"`
+}
+
+// Checklist represents a checklist.
+// Since: Bot API 9.1
+type Checklist struct {
+	Title                    string          `json:"title"`
+	TitleEntities            []MessageEntity `json:"title_entities,omitempty"`
+	Tasks                    []ChecklistTask `json:"tasks"`
+	OthersCanAddTasks        bool            `json:"others_can_add_tasks,omitempty"`
+	OthersCanMarkTasksAsDone bool            `json:"others_can_mark_tasks_as_done,omitempty"`
+}
+
+// InputChecklistTask describes a task in a checklist.
+// Since: Bot API 9.1
+type InputChecklistTask struct {
+	ID           int             `json:"id"`
+	Text         string          `json:"text"`
+	ParseMode    ParseMode       `json:"parse_mode,omitempty"`
+	TextEntities []MessageEntity `json:"text_entities,omitempty"`
+}
+
+// InputChecklist represents a checklist to be sent.
+// Since: Bot API 9.1
+type InputChecklist struct {
+	Title                   string               `json:"title"`
+	ParseMode               ParseMode            `json:"parse_mode,omitempty"`
+	TitleEntities           []MessageEntity      `json:"title_entities,omitempty"`
+	Tasks                   []InputChecklistTask `json:"tasks"`
+	OtherCanAddTasks        bool                 `json:"other_can_add_tasks,omitempty"`
+	OtherCanMarkTasksAsDone bool                 `json:"other_can_mark_tasks_as_done,omitempty"`
+}
+
+// ChecklistTaskDone describes a service message about checklist tasks being marked as done.
+// Since: Bot API 9.1
+type ChecklistTaskDone struct {
+	ChecklistMessage       *Message `json:"checklist_message,omitempty"`
+	MarkedAsDoneTaskIDs    []int    `json:"marked_as_done_task_ids,omitempty"`
+	MarkedAsNotDoneTaskIDs []int    `json:"marked_as_not_done_task_ids,omitempty"`
+}
+
+// ChecklistTasksAdded describes a service message about new checklist tasks being added.
+// Since: Bot API 9.1
+type ChecklistTasksAdded struct {
+	ChecklistMessage *Message        `json:"checklist_message,omitempty"`
+	Tasks            []ChecklistTask `json:"tasks"`
+}
+
 // InputMediaType represents the type of input media.
 type InputMediaType string
 
@@ -14,10 +342,16 @@ const (
 	InputMediaTypeVideo InputMediaType = "video"
 	// InputMediaTypeAudio is an audio file.
 	InputMediaTypeAudio InputMediaType = "audio"
+
+	InputMediaTypeSticker   InputMediaType = "sticker"
+	InputMediaTypeLocation  InputMediaType = "location"
+	InputMediaTypeVenue     InputMediaType = "venue"
+	InputMediaTypeLivePhoto InputMediaType = "live_photo" // Since: Bot API 10.0
 )
 
 // InputMedia represents the content of a media message to be sent.
-// It is a union type described in https://core.telegram.org/bots/api#inputmedia.
+// Since: Bot API 4.0
+// See https://core.telegram.org/bots/api#inputmedia
 type InputMedia struct {
 	Type  InputMediaType `json:"type"`
 	Media string         `json:"media"`
@@ -25,11 +359,11 @@ type InputMedia struct {
 	Caption               *string         `json:"caption,omitempty"`
 	ParseMode             *ParseMode      `json:"parse_mode,omitempty"`
 	CaptionEntities       []MessageEntity `json:"caption_entities,omitempty"`
-	ShowCaptionAboveMedia *bool           `json:"show_caption_above_media,omitempty"`
+	ShowCaptionAboveMedia *bool           `json:"show_caption_above_media,omitempty"` // Since: Bot API 7.4
-	HasSpoiler            *bool           `json:"has_spoiler,omitempty"`
+	HasSpoiler            *bool           `json:"has_spoiler,omitempty"`              // Since: Bot API 6.4
 
-	Cover             *string `json:"cover"`
+	Cover             *string `json:"cover"`           // Since: Bot API 8.3
-	StartTimestamp    *int    `json:"start_timestamp"`
+	StartTimestamp    *int    `json:"start_timestamp"` // Since: Bot API 8.3
 	Width             *int    `json:"width,omitempty"`
 	Height            *int    `json:"height,omitempty"`
 	Duration          *int    `json:"duration,omitempty"`
@@ -37,6 +371,18 @@ type InputMedia struct {
 
 	Performer *string `json:"performer,omitempty"`
 	Title     *string `json:"title,omitempty"`
+
+	Emoji *string `json:"emoji,omitempty"`
+
+	Latitude        *float64 `json:"latitude,omitempty"`
+	Longitude       *float64 `json:"longitude,omitempty"`
+	Address         *string  `json:"address,omitempty"`
+	FoursquareID    *string  `json:"foursquare_id,omitempty"`
+	FoursquareType  *string  `json:"foursquare_type,omitempty"`
+	GooglePlaceID   *string  `json:"google_place_id,omitempty"`
+	GooglePlaceType *string  `json:"google_place_type,omitempty"`
+
+	HorizontalAccuracy *float64 `json:"horizontal_accuracy,omitempty"`
 }
 
 // InputPaidMediaType represents the type of paid media.
@@ -47,16 +393,19 @@ const (
 	InputPaidMediaTypeVideo InputPaidMediaType = "video"
 	// InputPaidMediaTypePhoto represents a paid photo.
 	InputPaidMediaTypePhoto InputPaidMediaType = "photo"
+	// InputPaidMediaTypeLivePhoto represents a paid live photo.
+	InputPaidMediaTypeLivePhoto InputPaidMediaType = "live_photo" // Since: Bot API 10.0
 )
 
 // InputPaidMedia describes the paid media to be sent.
+// Since: Bot API 7.6
 // See https://core.telegram.org/bots/api#inputpaidmedia
 type InputPaidMedia struct {
 	Type  InputPaidMediaType `json:"type"`
 	Media string             `json:"media"`
 
-	Cover             *string `json:"cover,omitempty"`
+	Cover             *string `json:"cover,omitempty"`           // Since: Bot API 8.3
-	StartTimestamp    *int64  `json:"start_timestamp,omitempty"`
+	StartTimestamp    *int64  `json:"start_timestamp,omitempty"` // Since: Bot API 8.3
 	Width             *int    `json:"width,omitempty"`
 	Height            *int    `json:"height,omitempty"`
 	Duration          *int    `json:"duration,omitempty"`
@@ -64,6 +413,7 @@ type InputPaidMedia struct {
 }
 
 // PhotoSize represents one size of a photo or a file/sticker thumbnail.
+// Since: Bot API 1.0
 // See https://core.telegram.org/bots/api#photosize
 type PhotoSize struct {
 	FileID       string `json:"file_id"`
@@ -72,3 +422,16 @@ type PhotoSize struct {
 	Height       int    `json:"height"`
 	FileSize     int64  `json:"file_size,omitempty"`
 }
+
+// LivePhoto represents a live photo (a photo with a short video attached).
+// Since: Bot API 10.0
+type LivePhoto struct {
+	Photo        []PhotoSize `json:"photo,omitempty"`
+	FileID       string      `json:"file_id"`
+	FileUniqueID string      `json:"file_unique_id"`
+	Width        int         `json:"width"`
+	Height       int         `json:"height"`
+	Duration     int         `json:"duration"`
+	MIMEType     string      `json:"mime_type,omitempty"`
+	FileSize     int64       `json:"file_size,omitempty"`
+}

tgapi/bot_methods.go

@@ -2,54 +2,61 @@ package tgapi
 
 import "context"
 
-// SetMyCommandsP holds parameters for the setMyCommands method.
+// SetMyCommands holds parameters for the setMyCommands method.
+// Since: Bot API 4.7
 // See https://core.telegram.org/bots/api#setmycommands
-type SetMyCommandsP struct {
+type SetMyCommands struct {
 	Commands []BotCommand     `json:"commands"`
 	Scope    *BotCommandScope `json:"scope,omitempty"`
 	Language string           `json:"language_code,omitempty"`
 }
 
 // SetMyCommands changes the list of the bot's commands.
+// Since: Bot API 4.7
 // Returns true on success.
 // See https://core.telegram.org/bots/api#setmycommands
-func (api *API) SetMyCommands(params SetMyCommandsP) (bool, error) {
+func (api *API) SetMyCommands(params SetMyCommands) (bool, error) {
 	req := NewRequest[bool]("setMyCommands", params)
 	return req.Do(api)
 }
 
 // SetMyCommandsWithContext is the context-aware variant of SetMyCommands.
+// Since: Bot API 4.7
 // It executes the same request but uses ctx for cancellation and deadlines.
 // See https://core.telegram.org/bots/api#setmycommands
-func (api *API) SetMyCommandsWithContext(ctx context.Context, params SetMyCommandsP) (bool, error) {
+func (api *API) SetMyCommandsWithContext(ctx context.Context, params SetMyCommands) (bool, error) {
 	req := NewRequest[bool]("setMyCommands", params)
 	return req.DoWithContext(ctx, api)
 }
 
-// DeleteMyCommandsP holds parameters for the deleteMyCommands method.
+// DeleteMyCommands holds parameters for the deleteMyCommands method.
+// Since: Bot API 5.3
 // See https://core.telegram.org/bots/api#deletemycommands
-type DeleteMyCommandsP struct {
+type DeleteMyCommands struct {
 	Scope    *BotCommandScope `json:"scope,omitempty"`
 	Language string           `json:"language_code,omitempty"`
 }
 
 // DeleteMyCommands deletes the list of the bot's commands for the given scope and user language.
+// Since: Bot API 5.3
 // Returns true on success.
 // See https://core.telegram.org/bots/api#deletemycommands
-func (api *API) DeleteMyCommands(params DeleteMyCommandsP) (bool, error) {
+func (api *API) DeleteMyCommands(params DeleteMyCommands) (bool, error) {
 	req := NewRequest[bool]("deleteMyCommands", params)
 	return req.Do(api)
 }
 
 // DeleteMyCommandsWithContext is the context-aware variant of DeleteMyCommands.
+// Since: Bot API 5.3
 // It executes the same request but uses ctx for cancellation and deadlines.
 // See https://core.telegram.org/bots/api#deletemycommands
-func (api *API) DeleteMyCommandsWithContext(ctx context.Context, params DeleteMyCommandsP) (bool, error) {
+func (api *API) DeleteMyCommandsWithContext(ctx context.Context, params DeleteMyCommands) (bool, error) {
 	req := NewRequest[bool]("deleteMyCommands", params)
 	return req.DoWithContext(ctx, api)
 }
 
 // GetMyCommands holds parameters for the getMyCommands method.
+// Since: Bot API 4.7
 // See https://core.telegram.org/bots/api#getmycommands
 type GetMyCommands struct {
 	Scope    *BotCommandScope `json:"scope,omitempty"`
@@ -57,6 +64,7 @@ type GetMyCommands struct {
 }
 
 // GetMyCommands returns the current list of the bot's commands for the given scope and user language.
+// Since: Bot API 4.7
 // See https://core.telegram.org/bots/api#getmycommands
 func (api *API) GetMyCommands(params GetMyCommands) ([]BotCommand, error) {
 	req := NewRequest[[]BotCommand]("getMyCommands", params)
@@ -64,6 +72,7 @@ func (api *API) GetMyCommands(params GetMyCommands) ([]BotCommand, error) {
 }
 
 // GetMyCommandsWithContext is the context-aware variant of GetMyCommands.
+// Since: Bot API 4.7
 // It executes the same request but uses ctx for cancellation and deadlines.
 // See https://core.telegram.org/bots/api#getmycommands
 func (api *API) GetMyCommandsWithContext(ctx context.Context, params GetMyCommands) ([]BotCommand, error) {
@@ -72,6 +81,7 @@ func (api *API) GetMyCommandsWithContext(ctx context.Context, params GetMyComman
 }
 
 // SetMyName holds parameters for the setMyName method.
+// Since: Bot API 6.7
 // See https://core.telegram.org/bots/api#setmyname
 type SetMyName struct {
 	Name     string `json:"name"`
@@ -79,6 +89,7 @@ type SetMyName struct {
 }
 
 // SetMyName changes the bot's name.
+// Since: Bot API 6.7
 // Returns true on success.
 // See https://core.telegram.org/bots/api#setmyname
 func (api *API) SetMyName(params SetMyName) (bool, error) {
@@ -87,6 +98,7 @@ func (api *API) SetMyName(params SetMyName) (bool, error) {
 }
 
 // SetMyNameWithContext is the context-aware variant of SetMyName.
+// Since: Bot API 6.7
 // It executes the same request but uses ctx for cancellation and deadlines.
 // See https://core.telegram.org/bots/api#setmyname
 func (api *API) SetMyNameWithContext(ctx context.Context, params SetMyName) (bool, error) {
@@ -95,12 +107,14 @@ func (api *API) SetMyNameWithContext(ctx context.Context, params SetMyName) (boo
 }
 
 // GetMyName holds parameters for the getMyName method.
+// Since: Bot API 6.7
 // See https://core.telegram.org/bots/api#getmyname
 type GetMyName struct {
 	Language string `json:"language_code,omitempty"`
 }
 
 // GetMyName returns the bot's name for the given language.
+// Since: Bot API 6.7
 // See https://core.telegram.org/bots/api#getmyname
 func (api *API) GetMyName(params GetMyName) (BotName, error) {
 	req := NewRequest[BotName]("getMyName", params)
@@ -108,6 +122,7 @@ func (api *API) GetMyName(params GetMyName) (BotName, error) {
 }
 
 // GetMyNameWithContext is the context-aware variant of GetMyName.
+// Since: Bot API 6.7
 // It executes the same request but uses ctx for cancellation and deadlines.
 // See https://core.telegram.org/bots/api#getmyname
 func (api *API) GetMyNameWithContext(ctx context.Context, params GetMyName) (BotName, error) {
@@ -116,6 +131,7 @@ func (api *API) GetMyNameWithContext(ctx context.Context, params GetMyName) (Bot
 }
 
 // SetMyDescription holds parameters for the setMyDescription method.
+// Since: Bot API 6.6
 // See https://core.telegram.org/bots/api#setmydescription
 type SetMyDescription struct {
 	Description string `json:"description"`
@@ -123,6 +139,7 @@ type SetMyDescription struct {
 }
 
 // SetMyDescription changes the bot's description.
+// Since: Bot API 6.6
 // Returns true on success.
 // See https://core.telegram.org/bots/api#setmydescription
 func (api *API) SetMyDescription(params SetMyDescription) (bool, error) {
@@ -131,6 +148,7 @@ func (api *API) SetMyDescription(params SetMyDescription) (bool, error) {
 }
 
 // SetMyDescriptionWithContext is the context-aware variant of SetMyDescription.
+// Since: Bot API 6.6
 // It executes the same request but uses ctx for cancellation and deadlines.
 // See https://core.telegram.org/bots/api#setmydescription
 func (api *API) SetMyDescriptionWithContext(ctx context.Context, params SetMyDescription) (bool, error) {
@@ -139,12 +157,14 @@ func (api *API) SetMyDescriptionWithContext(ctx context.Context, params SetMyDes
 }
 
 // GetMyDescription holds parameters for the getMyDescription method.
+// Since: Bot API 6.6
 // See https://core.telegram.org/bots/api#getmydescription
 type GetMyDescription struct {
 	Language string `json:"language_code,omitempty"`
 }
 
 // GetMyDescription returns the bot's description for the given language.
+// Since: Bot API 6.6
 // See https://core.telegram.org/bots/api#getmydescription
 func (api *API) GetMyDescription(params GetMyDescription) (BotDescription, error) {
 	req := NewRequest[BotDescription]("getMyDescription", params)
@@ -152,6 +172,7 @@ func (api *API) GetMyDescription(params GetMyDescription) (BotDescription, error
 }
 
 // GetMyDescriptionWithContext is the context-aware variant of GetMyDescription.
+// Since: Bot API 6.6
 // It executes the same request but uses ctx for cancellation and deadlines.
 // See https://core.telegram.org/bots/api#getmydescription
 func (api *API) GetMyDescriptionWithContext(ctx context.Context, params GetMyDescription) (BotDescription, error) {
@@ -160,6 +181,7 @@ func (api *API) GetMyDescriptionWithContext(ctx context.Context, params GetMyDes
 }
 
 // SetMyShortDescription holds parameters for the setMyShortDescription method.
+// Since: Bot API 6.6
 // See https://core.telegram.org/bots/api#setmyshortdescription
 type SetMyShortDescription struct {
 	ShortDescription string `json:"short_description,omitempty"`
@@ -167,6 +189,7 @@ type SetMyShortDescription struct {
 }
 
 // SetMyShortDescription changes the bot's short description.
+// Since: Bot API 6.6
 // Returns true on success.
 // See https://core.telegram.org/bots/api#setmyshortdescription
 func (api *API) SetMyShortDescription(params SetMyShortDescription) (bool, error) {
@@ -175,6 +198,7 @@ func (api *API) SetMyShortDescription(params SetMyShortDescription) (bool, error
 }
 
 // SetMyShortDescriptionWithContext is the context-aware variant of SetMyShortDescription.
+// Since: Bot API 6.6
 // It executes the same request but uses ctx for cancellation and deadlines.
 // See https://core.telegram.org/bots/api#setmyshortdescription
 func (api *API) SetMyShortDescriptionWithContext(ctx context.Context, params SetMyShortDescription) (bool, error) {
@@ -183,12 +207,14 @@ func (api *API) SetMyShortDescriptionWithContext(ctx context.Context, params Set
 }
 
 // GetMyShortDescription holds parameters for the getMyShortDescription method.
+// Since: Bot API 6.6
 // See https://core.telegram.org/bots/api#getmyshortdescription
 type GetMyShortDescription struct {
 	Language string `json:"language_code,omitempty"`
 }
 
 // GetMyShortDescription returns the bot's short description for the given language.
+// Since: Bot API 6.6
 // See https://core.telegram.org/bots/api#getmyshortdescription
 func (api *API) GetMyShortDescription(params GetMyShortDescription) (BotShortDescription, error) {
 	req := NewRequest[BotShortDescription]("getMyShortDescription", params)
@@ -196,6 +222,7 @@ func (api *API) GetMyShortDescription(params GetMyShortDescription) (BotShortDes
 }
 
 // GetMyShortDescriptionWithContext is the context-aware variant of GetMyShortDescription.
+// Since: Bot API 6.6
 // It executes the same request but uses ctx for cancellation and deadlines.
 // See https://core.telegram.org/bots/api#getmyshortdescription
 func (api *API) GetMyShortDescriptionWithContext(ctx context.Context, params GetMyShortDescription) (BotShortDescription, error) {
@@ -203,29 +230,33 @@ func (api *API) GetMyShortDescriptionWithContext(ctx context.Context, params Get
 	return req.DoWithContext(ctx, api)
 }
 
-// SetMyProfilePhotoP holds parameters for the setMyProfilePhoto method.
+// SetMyProfilePhoto holds parameters for the setMyProfilePhoto method.
+// Since: Bot API 9.0
 // See https://core.telegram.org/bots/api#setmyprofilephoto
-type SetMyProfilePhotoP struct {
+type SetMyProfilePhoto struct {
 	Photo InputProfilePhoto `json:"photo"`
 }
 
 // SetMyProfilePhoto changes the bot's profile photo.
+// Since: Bot API 9.0
 // Returns true on success.
 // See https://core.telegram.org/bots/api#setmyprofilephoto
-func (api *API) SetMyProfilePhoto(params SetMyProfilePhotoP) (bool, error) {
+func (api *API) SetMyProfilePhoto(params SetMyProfilePhoto) (bool, error) {
 	req := NewRequest[bool]("setMyProfilePhoto", params)
 	return req.Do(api)
 }
 
 // SetMyProfilePhotoWithContext is the context-aware variant of SetMyProfilePhoto.
+// Since: Bot API 9.0
 // It executes the same request but uses ctx for cancellation and deadlines.
 // See https://core.telegram.org/bots/api#setmyprofilephoto
-func (api *API) SetMyProfilePhotoWithContext(ctx context.Context, params SetMyProfilePhotoP) (bool, error) {
+func (api *API) SetMyProfilePhotoWithContext(ctx context.Context, params SetMyProfilePhoto) (bool, error) {
 	req := NewRequest[bool]("setMyProfilePhoto", params)
 	return req.DoWithContext(ctx, api)
 }
 
 // RemoveMyProfilePhoto removes the bot's profile photo.
+// Since: Bot API 9.0
 // Returns true on success.
 // See https://core.telegram.org/bots/api#removemyprofilephoto
 func (api *API) RemoveMyProfilePhoto() (bool, error) {
@@ -234,6 +265,7 @@ func (api *API) RemoveMyProfilePhoto() (bool, error) {
 }
 
 // RemoveMyProfilePhotoWithContext is the context-aware variant of RemoveMyProfilePhoto.
+// Since: Bot API 9.0
 // It executes the same request but uses ctx for cancellation and deadlines.
 // See https://core.telegram.org/bots/api#removemyprofilephoto
 func (api *API) RemoveMyProfilePhotoWithContext(ctx context.Context) (bool, error) {
@@ -241,95 +273,108 @@ func (api *API) RemoveMyProfilePhotoWithContext(ctx context.Context) (bool, erro
 	return req.DoWithContext(ctx, api)
 }
 
-// SetChatMenuButtonP holds parameters for the setChatMenuButton method.
+// SetChatMenuButton holds parameters for the setChatMenuButton method.
+// Since: Bot API 6.0
 // See https://core.telegram.org/bots/api#setchatmenubutton
-type SetChatMenuButtonP struct {
+type SetChatMenuButton struct {
-	ChatID     int64          `json:"chat_id,omitempty"`
+	ChatID     int64       `json:"chat_id,omitempty"`
-	MenuButton MenuButtonType `json:"menu_button"`
+	MenuButton *MenuButton `json:"menu_button,omitempty"`
 }
 
 // SetChatMenuButton changes the menu button for a given chat or the default menu button.
+// Since: Bot API 6.0
 // Returns true on success.
 // See https://core.telegram.org/bots/api#setchatmenubutton
-func (api *API) SetChatMenuButton(params SetChatMenuButtonP) (bool, error) {
+func (api *API) SetChatMenuButton(params SetChatMenuButton) (bool, error) {
 	req := NewRequest[bool]("setChatMenuButton", params)
 	return req.Do(api)
 }
 
 // SetChatMenuButtonWithContext is the context-aware variant of SetChatMenuButton.
+// Since: Bot API 6.0
 // It executes the same request but uses ctx for cancellation and deadlines.
 // See https://core.telegram.org/bots/api#setchatmenubutton
-func (api *API) SetChatMenuButtonWithContext(ctx context.Context, params SetChatMenuButtonP) (bool, error) {
+func (api *API) SetChatMenuButtonWithContext(ctx context.Context, params SetChatMenuButton) (bool, error) {
 	req := NewRequest[bool]("setChatMenuButton", params)
 	return req.DoWithContext(ctx, api)
 }
 
-// GetChatMenuButtonP holds parameters for the getChatMenuButton method.
+// GetChatMenuButton holds parameters for the getChatMenuButton method.
+// Since: Bot API 6.0
 // See https://core.telegram.org/bots/api#getchatmenubutton
-type GetChatMenuButtonP struct {
+type GetChatMenuButton struct {
 	ChatID int64 `json:"chat_id,omitempty"`
 }
 
 // GetChatMenuButton returns the current menu button for the given chat.
+// Since: Bot API 6.0
 // See https://core.telegram.org/bots/api#getchatmenubutton
-func (api *API) GetChatMenuButton(params GetChatMenuButtonP) (MenuButton, error) {
+func (api *API) GetChatMenuButton(params GetChatMenuButton) (MenuButton, error) {
 	req := NewRequest[MenuButton]("getChatMenuButton", params)
 	return req.Do(api)
 }
 
 // GetChatMenuButtonWithContext is the context-aware variant of GetChatMenuButton.
+// Since: Bot API 6.0
 // It executes the same request but uses ctx for cancellation and deadlines.
 // See https://core.telegram.org/bots/api#getchatmenubutton
-func (api *API) GetChatMenuButtonWithContext(ctx context.Context, params GetChatMenuButtonP) (MenuButton, error) {
+func (api *API) GetChatMenuButtonWithContext(ctx context.Context, params GetChatMenuButton) (MenuButton, error) {
 	req := NewRequest[MenuButton]("getChatMenuButton", params)
 	return req.DoWithContext(ctx, api)
 }
 
-// SetMyDefaultAdministratorRightsP holds parameters for the setMyDefaultAdministratorRights method.
+// SetMyDefaultAdministratorRights holds parameters for the setMyDefaultAdministratorRights method.
+// Since: Bot API 6.0
 // See https://core.telegram.org/bots/api#setmydefaultadministratorrights
-type SetMyDefaultAdministratorRightsP struct {
+type SetMyDefaultAdministratorRights struct {
 	Rights      *ChatAdministratorRights `json:"rights"`
 	ForChannels bool                     `json:"for_channels"`
 }
 
 // SetMyDefaultAdministratorRights changes the default administrator rights for the bot.
+// Since: Bot API 6.0
 // Returns true on success.
 // See https://core.telegram.org/bots/api#setmydefaultadministratorrights
-func (api *API) SetMyDefaultAdministratorRights(params SetMyDefaultAdministratorRightsP) (bool, error) {
+func (api *API) SetMyDefaultAdministratorRights(params SetMyDefaultAdministratorRights) (bool, error) {
 	req := NewRequest[bool]("setMyDefaultAdministratorRights", params)
 	return req.Do(api)
 }
 
 // SetMyDefaultAdministratorRightsWithContext is the context-aware variant of SetMyDefaultAdministratorRights.
+// Since: Bot API 6.0
 // It executes the same request but uses ctx for cancellation and deadlines.
 // See https://core.telegram.org/bots/api#setmydefaultadministratorrights
-func (api *API) SetMyDefaultAdministratorRightsWithContext(ctx context.Context, params SetMyDefaultAdministratorRightsP) (bool, error) {
+func (api *API) SetMyDefaultAdministratorRightsWithContext(ctx context.Context, params SetMyDefaultAdministratorRights) (bool, error) {
 	req := NewRequest[bool]("setMyDefaultAdministratorRights", params)
 	return req.DoWithContext(ctx, api)
 }
 
-// GetMyDefaultAdministratorRightsP holds parameters for the getMyDefaultAdministratorRights method.
+// GetMyDefaultAdministratorRights holds parameters for the getMyDefaultAdministratorRights method.
+// Since: Bot API 6.0
 // See https://core.telegram.org/bots/api#getmydefaultadministratorrights
-type GetMyDefaultAdministratorRightsP struct {
+type GetMyDefaultAdministratorRights struct {
 	ForChannels bool `json:"for_channels"`
 }
 
 // GetMyDefaultAdministratorRights returns the current default administrator rights for the bot.
+// Since: Bot API 6.0
 // See https://core.telegram.org/bots/api#getmydefaultadministratorrights
-func (api *API) GetMyDefaultAdministratorRights(params GetMyDefaultAdministratorRightsP) (ChatAdministratorRights, error) {
+func (api *API) GetMyDefaultAdministratorRights(params GetMyDefaultAdministratorRights) (ChatAdministratorRights, error) {
 	req := NewRequest[ChatAdministratorRights]("getMyDefaultAdministratorRights", params)
 	return req.Do(api)
 }
 
 // GetMyDefaultAdministratorRightsWithContext is the context-aware variant of GetMyDefaultAdministratorRights.
+// Since: Bot API 6.0
 // It executes the same request but uses ctx for cancellation and deadlines.
 // See https://core.telegram.org/bots/api#getmydefaultadministratorrights
-func (api *API) GetMyDefaultAdministratorRightsWithContext(ctx context.Context, params GetMyDefaultAdministratorRightsP) (ChatAdministratorRights, error) {
+func (api *API) GetMyDefaultAdministratorRightsWithContext(ctx context.Context, params GetMyDefaultAdministratorRights) (ChatAdministratorRights, error) {
 	req := NewRequest[ChatAdministratorRights]("getMyDefaultAdministratorRights", params)
 	return req.DoWithContext(ctx, api)
 }
 
 // GetAvailableGifts returns the list of gifts that can be sent by the bot.
+// Since: Bot API 9.0
 // See https://core.telegram.org/bots/api#getavailablegifts
 func (api *API) GetAvailableGifts() (Gifts, error) {
 	req := NewRequest[Gifts]("getAvailableGifts", NoParams)
@@ -337,6 +382,7 @@ func (api *API) GetAvailableGifts() (Gifts, error) {
 }
 
 // GetAvailableGiftsWithContext is the context-aware variant of GetAvailableGifts.
+// Since: Bot API 9.0
 // It executes the same request but uses ctx for cancellation and deadlines.
 // See https://core.telegram.org/bots/api#getavailablegifts
 func (api *API) GetAvailableGiftsWithContext(ctx context.Context) (Gifts, error) {
@@ -344,9 +390,10 @@ func (api *API) GetAvailableGiftsWithContext(ctx context.Context) (Gifts, error)
 	return req.DoWithContext(ctx, api)
 }
 
-// SendGiftP holds parameters for the sendGift method.
+// SendGift holds parameters for the sendGift method.
+// Since: Bot API 9.0
 // See https://core.telegram.org/bots/api#sendgift
-type SendGiftP struct {
+type SendGift struct {
 	UserID        int64           `json:"user_id,omitempty"`
 	ChatID        int64           `json:"chat_id,omitempty"`
 	GiftID        string          `json:"gift_id"`
@@ -357,24 +404,27 @@ type SendGiftP struct {
 }
 
 // SendGift sends a gift to the given user or chat.
+// Since: Bot API 9.0
 // Returns true on success.
 // See https://core.telegram.org/bots/api#sendgift
-func (api *API) SendGift(params SendGiftP) (bool, error) {
+func (api *API) SendGift(params SendGift) (bool, error) {
 	req := NewRequest[bool]("sendGift", params)
 	return req.Do(api)
 }
 
 // SendGiftWithContext is the context-aware variant of SendGift.
+// Since: Bot API 9.0
 // It executes the same request but uses ctx for cancellation and deadlines.
 // See https://core.telegram.org/bots/api#sendgift
-func (api *API) SendGiftWithContext(ctx context.Context, params SendGiftP) (bool, error) {
+func (api *API) SendGiftWithContext(ctx context.Context, params SendGift) (bool, error) {
 	req := NewRequest[bool]("sendGift", params)
 	return req.DoWithContext(ctx, api)
 }
 
-// GiftPremiumSubscriptionP holds parameters for the giftPremiumSubscription method.
+// GiftPremiumSubscription holds parameters for the giftPremiumSubscription method.
+// Since: Bot API 9.0
 // See https://core.telegram.org/bots/api#giftpremiumsubscription
-type GiftPremiumSubscriptionP struct {
+type GiftPremiumSubscription struct {
 	UserID        int64           `json:"user_id"`
 	MonthCount    int             `json:"month_count"`
 	StarCount     int             `json:"star_count"`
@@ -384,17 +434,69 @@ type GiftPremiumSubscriptionP struct {
 }
 
 // GiftPremiumSubscription gifts a Telegram Premium subscription to the user.
+// Since: Bot API 9.0
 // Returns true on success.
 // See https://core.telegram.org/bots/api#giftpremiumsubscription
-func (api *API) GiftPremiumSubscription(params GiftPremiumSubscriptionP) (bool, error) {
+func (api *API) GiftPremiumSubscription(params GiftPremiumSubscription) (bool, error) {
 	req := NewRequest[bool]("giftPremiumSubscription", params)
 	return req.Do(api)
 }
 
 // GiftPremiumSubscriptionWithContext is the context-aware variant of GiftPremiumSubscription.
+// Since: Bot API 9.0
 // It executes the same request but uses ctx for cancellation and deadlines.
 // See https://core.telegram.org/bots/api#giftpremiumsubscription
-func (api *API) GiftPremiumSubscriptionWithContext(ctx context.Context, params GiftPremiumSubscriptionP) (bool, error) {
+func (api *API) GiftPremiumSubscriptionWithContext(ctx context.Context, params GiftPremiumSubscription) (bool, error) {
 	req := NewRequest[bool]("giftPremiumSubscription", params)
 	return req.DoWithContext(ctx, api)
 }
+
+// GetManagedBotAccessSettings holds parameters for the getManagedBotAccessSettings method.
+// Since: Bot API 10.0
+// See https://core.telegram.org/bots/api#getmanagedbotaccesssettings
+type GetManagedBotAccessSettings struct {
+	BotUserID int64 `json:"bot_user_id"`
+}
+
+// GetManagedBotAccessSettings returns the access settings of a managed bot.
+// Since: Bot API 10.0
+// See https://core.telegram.org/bots/api#getmanagedbotaccesssettings
+func (api *API) GetManagedBotAccessSettings(params GetManagedBotAccessSettings) (BotAccessSettings, error) {
+	req := NewRequest[BotAccessSettings]("getManagedBotAccessSettings", params)
+	return req.Do(api)
+}
+
+// GetManagedBotAccessSettingsWithContext is the context-aware variant of GetManagedBotAccessSettings.
+// Since: Bot API 10.0
+// It executes the same request but uses ctx for cancellation and deadlines.
+// See https://core.telegram.org/bots/api#getmanagedbotaccesssettings
+func (api *API) GetManagedBotAccessSettingsWithContext(ctx context.Context, params GetManagedBotAccessSettings) (BotAccessSettings, error) {
+	req := NewRequest[BotAccessSettings]("getManagedBotAccessSettings", params)
+	return req.DoWithContext(ctx, api)
+}
+
+// SetManagedBotAccessSettings holds parameters for the setManagedBotAccessSettings method.
+// Since: Bot API 10.0
+// See https://core.telegram.org/bots/api#setmanagedbotaccesssettings
+type SetManagedBotAccessSettings struct {
+	BotUserID      int64             `json:"bot_user_id"`
+	AccessSettings BotAccessSettings `json:"access_settings"`
+}
+
+// SetManagedBotAccessSettings changes the access settings of a managed bot.
+// Since: Bot API 10.0
+// Returns True on success.
+// See https://core.telegram.org/bots/api#setmanagedbotaccesssettings
+func (api *API) SetManagedBotAccessSettings(params SetManagedBotAccessSettings) (bool, error) {
+	req := NewRequest[bool]("setManagedBotAccessSettings", params)
+	return req.Do(api)
+}
+
+// SetManagedBotAccessSettingsWithContext is the context-aware variant of SetManagedBotAccessSettings.
+// Since: Bot API 10.0
+// It executes the same request but uses ctx for cancellation and deadlines.
+// See https://core.telegram.org/bots/api#setmanagedbotaccesssettings
+func (api *API) SetManagedBotAccessSettingsWithContext(ctx context.Context, params SetManagedBotAccessSettings) (bool, error) {
+	req := NewRequest[bool]("setManagedBotAccessSettings", params)
+	return req.DoWithContext(ctx, api)
+}

tgapi/bot_types.go

@@ -1,6 +1,7 @@
 package tgapi
 
 // BotCommand represents a bot command.
+// Since: Bot API 4.7
 // See https://core.telegram.org/bots/api#botcommand
 type BotCommand struct {
 	Command     string `json:"command"`
@@ -28,6 +29,7 @@ const (
 )
 
 // BotCommandScope represents the scope to which bot commands are applied.
+// Since: Bot API 5.3
 // See https://core.telegram.org/bots/api#botcommandscope
 type BotCommandScope struct {
 	Type   BotCommandScopeType `json:"type"`
@@ -36,16 +38,19 @@ type BotCommandScope struct {
 }
 
 // BotName represents the bot's name.
+// Since: Bot API 6.7
 type BotName struct {
 	Name string `json:"name"`
 }
 
 // BotDescription represents the bot's description.
+// Since: Bot API 6.6
 type BotDescription struct {
 	Description string `json:"description"`
 }
 
 // BotShortDescription represents the bot's short description.
+// Since: Bot API 6.6
 type BotShortDescription struct {
 	ShortDescription string `json:"short_description"`
 }
@@ -61,6 +66,7 @@ const (
 )
 
 // InputProfilePhoto describes a profile photo to set.
+// Since: Bot API 9.0
 // See https://core.telegram.org/bots/api#inputprofilephoto
 type InputProfilePhoto struct {
 	Type InputProfilePhotoType `json:"type"`
@@ -86,6 +92,7 @@ const (
 )
 
 // MenuButton represents a menu button.
+// Since: Bot API 6.0
 // See https://core.telegram.org/bots/api#menubutton
 type MenuButton struct {
 	Type MenuButtonType `json:"type"`
@@ -94,3 +101,10 @@ type MenuButton struct {
 	Text   *string     `json:"text"`
 	WebApp *WebAppInfo `json:"web_app"`
 }
+
+// BotAccessSettings describes access settings of a managed bot.
+// Since: Bot API 10.0
+// See https://core.telegram.org/bots/api#botaccesssettings
+type BotAccessSettings struct {
+	AllowAllPrivateChats bool `json:"allow_all_private_chats"`
+}

tgapi/business_methods.go

@@ -2,235 +2,266 @@ package tgapi
 
 import "context"
 
-// VerifyUserP holds parameters for the verifyUser method.
+// VerifyUser holds parameters for the verifyUser method.
+// Since: Bot API 8.0
 // See https://core.telegram.org/bots/api#verifyuser
-type VerifyUserP struct {
+type VerifyUser struct {
 	UserID            int64  `json:"user_id"`
 	CustomDescription string `json:"custom_description,omitempty"`
 }
 
 // VerifyUser verifies a user.
+// Since: Bot API 8.0
 // Returns true on success.
 // See https://core.telegram.org/bots/api#verifyuser
-func (api *API) VerifyUser(params VerifyUserP) (bool, error) {
+func (api *API) VerifyUser(params VerifyUser) (bool, error) {
 	req := NewRequest[bool]("verifyUser", params)
 	return req.Do(api)
 }
 
 // VerifyUserWithContext is the context-aware variant of VerifyUser.
+// Since: Bot API 8.0
 // It executes the same request but uses ctx for cancellation and deadlines.
 // See https://core.telegram.org/bots/api#verifyuser
-func (api *API) VerifyUserWithContext(ctx context.Context, params VerifyUserP) (bool, error) {
+func (api *API) VerifyUserWithContext(ctx context.Context, params VerifyUser) (bool, error) {
 	req := NewRequest[bool]("verifyUser", params)
 	return req.DoWithContext(ctx, api)
 }
 
-// VerifyChatP holds parameters for the verifyChat method.
+// VerifyChat holds parameters for the verifyChat method.
+// Since: Bot API 8.0
 // See https://core.telegram.org/bots/api#verifychat
-type VerifyChatP struct {
+type VerifyChat struct {
 	ChatID            int64  `json:"chat_id"`
 	CustomDescription string `json:"custom_description,omitempty"`
 }
 
 // VerifyChat verifies a chat.
+// Since: Bot API 8.0
 // Returns true on success.
 // See https://core.telegram.org/bots/api#verifychat
-func (api *API) VerifyChat(params VerifyChatP) (bool, error) {
+func (api *API) VerifyChat(params VerifyChat) (bool, error) {
 	req := NewRequest[bool]("verifyChat", params)
 	return req.Do(api)
 }
 
 // VerifyChatWithContext is the context-aware variant of VerifyChat.
+// Since: Bot API 8.0
 // It executes the same request but uses ctx for cancellation and deadlines.
 // See https://core.telegram.org/bots/api#verifychat
-func (api *API) VerifyChatWithContext(ctx context.Context, params VerifyChatP) (bool, error) {
+func (api *API) VerifyChatWithContext(ctx context.Context, params VerifyChat) (bool, error) {
 	req := NewRequest[bool]("verifyChat", params)
 	return req.DoWithContext(ctx, api)
 }
 
-// RemoveUserVerificationP holds parameters for the removeUserVerification method.
+// RemoveUserVerification holds parameters for the removeUserVerification method.
+// Since: Bot API 8.0
 // See https://core.telegram.org/bots/api#removeuserverification
-type RemoveUserVerificationP struct {
+type RemoveUserVerification struct {
 	UserID int64 `json:"user_id"`
 }
 
 // RemoveUserVerification removes a user's verification.
+// Since: Bot API 8.0
 // Returns true on success.
 // See https://core.telegram.org/bots/api#removeuserverification
-func (api *API) RemoveUserVerification(params RemoveUserVerificationP) (bool, error) {
+func (api *API) RemoveUserVerification(params RemoveUserVerification) (bool, error) {
 	req := NewRequest[bool]("removeUserVerification", params)
 	return req.Do(api)
 }
 
 // RemoveUserVerificationWithContext is the context-aware variant of RemoveUserVerification.
+// Since: Bot API 8.0
 // It executes the same request but uses ctx for cancellation and deadlines.
 // See https://core.telegram.org/bots/api#removeuserverification
-func (api *API) RemoveUserVerificationWithContext(ctx context.Context, params RemoveUserVerificationP) (bool, error) {
+func (api *API) RemoveUserVerificationWithContext(ctx context.Context, params RemoveUserVerification) (bool, error) {
 	req := NewRequest[bool]("removeUserVerification", params)
 	return req.DoWithContext(ctx, api)
 }
 
-// RemoveChatVerificationP holds parameters for the removeChatVerification method.
+// RemoveChatVerification holds parameters for the removeChatVerification method.
+// Since: Bot API 8.0
 // See https://core.telegram.org/bots/api#removechatverification
-type RemoveChatVerificationP struct {
+type RemoveChatVerification struct {
 	ChatID int64 `json:"chat_id"`
 }
 
 // RemoveChatVerification removes a chat's verification.
+// Since: Bot API 8.0
 // Returns true on success.
 // See https://core.telegram.org/bots/api#removechatverification
-func (api *API) RemoveChatVerification(params RemoveChatVerificationP) (bool, error) {
+func (api *API) RemoveChatVerification(params RemoveChatVerification) (bool, error) {
 	req := NewRequest[bool]("removeChatVerification", params)
 	return req.Do(api)
 }
 
 // RemoveChatVerificationWithContext is the context-aware variant of RemoveChatVerification.
+// Since: Bot API 8.0
 // It executes the same request but uses ctx for cancellation and deadlines.
 // See https://core.telegram.org/bots/api#removechatverification
-func (api *API) RemoveChatVerificationWithContext(ctx context.Context, params RemoveChatVerificationP) (bool, error) {
+func (api *API) RemoveChatVerificationWithContext(ctx context.Context, params RemoveChatVerification) (bool, error) {
 	req := NewRequest[bool]("removeChatVerification", params)
 	return req.DoWithContext(ctx, api)
 }
 
-// ReadBusinessMessageP holds parameters for the readBusinessMessage method.
+// ReadBusinessMessage holds parameters for the readBusinessMessage method.
+// Since: Bot API 9.0
 // See https://core.telegram.org/bots/api#readbusinessmessage
-type ReadBusinessMessageP struct {
+type ReadBusinessMessage struct {
 	BusinessConnectionID string `json:"business_connection_id"`
 	ChatID               int64  `json:"chat_id"`
 	MessageID            int    `json:"message_id"`
 }
 
 // ReadBusinessMessage marks a business message as read.
+// Since: Bot API 9.0
 // Returns true on success.
 // See https://core.telegram.org/bots/api#readbusinessmessage
-func (api *API) ReadBusinessMessage(params ReadBusinessMessageP) (bool, error) {
+func (api *API) ReadBusinessMessage(params ReadBusinessMessage) (bool, error) {
 	req := NewRequest[bool]("readBusinessMessage", params)
 	return req.Do(api)
 }
 
 // ReadBusinessMessageWithContext is the context-aware variant of ReadBusinessMessage.
+// Since: Bot API 9.0
 // It executes the same request but uses ctx for cancellation and deadlines.
 // See https://core.telegram.org/bots/api#readbusinessmessage
-func (api *API) ReadBusinessMessageWithContext(ctx context.Context, params ReadBusinessMessageP) (bool, error) {
+func (api *API) ReadBusinessMessageWithContext(ctx context.Context, params ReadBusinessMessage) (bool, error) {
 	req := NewRequest[bool]("readBusinessMessage", params)
 	return req.DoWithContext(ctx, api)
 }
 
-// GetBusinessConnectionP holds parameters for the getBusinessConnection method.
+// GetBusinessConnection holds parameters for the getBusinessConnection method.
+// Since: Bot API 7.2
 // See https://core.telegram.org/bots/api#getbusinessconnection
-type GetBusinessConnectionP struct {
+type GetBusinessConnection struct {
 	BusinessConnectionID string `json:"business_connection_id"`
 }
 
 // GetBusinessConnection returns information about a business connection.
+// Since: Bot API 7.2
 // See https://core.telegram.org/bots/api#getbusinessconnection
-func (api *API) GetBusinessConnection(params GetBusinessConnectionP) (BusinessConnection, error) {
+func (api *API) GetBusinessConnection(params GetBusinessConnection) (BusinessConnection, error) {
 	req := NewRequest[BusinessConnection]("getBusinessConnection", params)
 	return req.Do(api)
 }
 
 // GetBusinessConnectionWithContext is the context-aware variant of GetBusinessConnection.
+// Since: Bot API 7.2
 // It executes the same request but uses ctx for cancellation and deadlines.
 // See https://core.telegram.org/bots/api#getbusinessconnection
-func (api *API) GetBusinessConnectionWithContext(ctx context.Context, params GetBusinessConnectionP) (BusinessConnection, error) {
+func (api *API) GetBusinessConnectionWithContext(ctx context.Context, params GetBusinessConnection) (BusinessConnection, error) {
 	req := NewRequest[BusinessConnection]("getBusinessConnection", params)
 	return req.DoWithContext(ctx, api)
 }
 
-// DeleteBusinessMessagesP holds parameters for the deleteBusinessMessages method.
+// DeleteBusinessMessages holds parameters for the deleteBusinessMessages method.
+// Since: Bot API 9.0
 // See https://core.telegram.org/bots/api#deletebusinessmessages
-type DeleteBusinessMessagesP struct {
+type DeleteBusinessMessages struct {
 	BusinessConnectionID string `json:"business_connection_id"`
 	MessageIDs           []int  `json:"message_ids"`
 }
 
 // DeleteBusinessMessages deletes business messages.
+// Since: Bot API 9.0
 // Returns true on success.
 // See https://core.telegram.org/bots/api#deletebusinessmessages
-func (api *API) DeleteBusinessMessages(params DeleteBusinessMessagesP) (bool, error) {
+func (api *API) DeleteBusinessMessages(params DeleteBusinessMessages) (bool, error) {
 	req := NewRequest[bool]("deleteBusinessMessages", params)
 	return req.Do(api)
 }
 
 // DeleteBusinessMessagesWithContext is the context-aware variant of DeleteBusinessMessages.
+// Since: Bot API 9.0
 // It executes the same request but uses ctx for cancellation and deadlines.
 // See https://core.telegram.org/bots/api#deletebusinessmessages
-func (api *API) DeleteBusinessMessagesWithContext(ctx context.Context, params DeleteBusinessMessagesP) (bool, error) {
+func (api *API) DeleteBusinessMessagesWithContext(ctx context.Context, params DeleteBusinessMessages) (bool, error) {
 	req := NewRequest[bool]("deleteBusinessMessages", params)
 	return req.DoWithContext(ctx, api)
 }
 
-// SetBusinessAccountNameP holds parameters for the setBusinessAccountName method.
+// SetBusinessAccountName holds parameters for the setBusinessAccountName method.
+// Since: Bot API 9.0
 // See https://core.telegram.org/bots/api#setbusinessaccountname
-type SetBusinessAccountNameP struct {
+type SetBusinessAccountName struct {
 	BusinessConnectionID string `json:"business_connection_id"`
 	FirstName            string `json:"first_name"`
 	LastName             string `json:"last_name,omitempty"`
 }
 
 // SetBusinessAccountName sets the first and last name of a business account.
+// Since: Bot API 9.0
 // Returns true on success.
 // See https://core.telegram.org/bots/api#setbusinessaccountname
-func (api *API) SetBusinessAccountName(params SetBusinessAccountNameP) (bool, error) {
+func (api *API) SetBusinessAccountName(params SetBusinessAccountName) (bool, error) {
 	req := NewRequest[bool]("setBusinessAccountName", params)
 	return req.Do(api)
 }
 
 // SetBusinessAccountNameWithContext is the context-aware variant of SetBusinessAccountName.
+// Since: Bot API 9.0
 // It executes the same request but uses ctx for cancellation and deadlines.
 // See https://core.telegram.org/bots/api#setbusinessaccountname
-func (api *API) SetBusinessAccountNameWithContext(ctx context.Context, params SetBusinessAccountNameP) (bool, error) {
+func (api *API) SetBusinessAccountNameWithContext(ctx context.Context, params SetBusinessAccountName) (bool, error) {
 	req := NewRequest[bool]("setBusinessAccountName", params)
 	return req.DoWithContext(ctx, api)
 }
 
-// SetBusinessAccountUsernameP holds parameters for the setBusinessAccountUsername method.
+// SetBusinessAccountUsername holds parameters for the setBusinessAccountUsername method.
+// Since: Bot API 9.0
 // See https://core.telegram.org/bots/api#setbusinessaccountusername
-type SetBusinessAccountUsernameP struct {
+type SetBusinessAccountUsername struct {
 	BusinessConnectionID string `json:"business_connection_id"`
 	Username             string `json:"username,omitempty"`
 }
 
 // SetBusinessAccountUsername sets the username of a business account.
+// Since: Bot API 9.0
 // Returns true on success.
 // See https://core.telegram.org/bots/api#setbusinessaccountusername
-func (api *API) SetBusinessAccountUsername(params SetBusinessAccountUsernameP) (bool, error) {
+func (api *API) SetBusinessAccountUsername(params SetBusinessAccountUsername) (bool, error) {
 	req := NewRequest[bool]("setBusinessAccountUsername", params)
 	return req.Do(api)
 }
 
 // SetBusinessAccountUsernameWithContext is the context-aware variant of SetBusinessAccountUsername.
+// Since: Bot API 9.0
 // It executes the same request but uses ctx for cancellation and deadlines.
 // See https://core.telegram.org/bots/api#setbusinessaccountusername
-func (api *API) SetBusinessAccountUsernameWithContext(ctx context.Context, params SetBusinessAccountUsernameP) (bool, error) {
+func (api *API) SetBusinessAccountUsernameWithContext(ctx context.Context, params SetBusinessAccountUsername) (bool, error) {
 	req := NewRequest[bool]("setBusinessAccountUsername", params)
 	return req.DoWithContext(ctx, api)
 }
 
-// SetBusinessAccountBioP holds parameters for the setBusinessAccountBio method.
+// SetBusinessAccountBio holds parameters for the setBusinessAccountBio method.
+// Since: Bot API 9.0
 // See https://core.telegram.org/bots/api#setbusinessaccountbio
-type SetBusinessAccountBioP struct {
+type SetBusinessAccountBio struct {
 	BusinessConnectionID string `json:"business_connection_id"`
 	Bio                  string `json:"bio,omitempty"`
 }
 
 // SetBusinessAccountBio sets the bio of a business account.
+// Since: Bot API 9.0
 // Returns true on success.
 // See https://core.telegram.org/bots/api#setbusinessaccountbio
-func (api *API) SetBusinessAccountBio(params SetBusinessAccountBioP) (bool, error) {
+func (api *API) SetBusinessAccountBio(params SetBusinessAccountBio) (bool, error) {
 	req := NewRequest[bool]("setBusinessAccountBio", params)
 	return req.Do(api)
 }
 
 // SetBusinessAccountBioWithContext is the context-aware variant of SetBusinessAccountBio.
+// Since: Bot API 9.0
 // It executes the same request but uses ctx for cancellation and deadlines.
 // See https://core.telegram.org/bots/api#setbusinessaccountbio
-func (api *API) SetBusinessAccountBioWithContext(ctx context.Context, params SetBusinessAccountBioP) (bool, error) {
+func (api *API) SetBusinessAccountBioWithContext(ctx context.Context, params SetBusinessAccountBio) (bool, error) {
 	req := NewRequest[bool]("setBusinessAccountBio", params)
 	return req.DoWithContext(ctx, api)
 }
 
 // SetBusinessAccountProfilePhoto holds parameters for the setBusinessAccountProfilePhoto method.
+// Since: Bot API 9.0
 // See https://core.telegram.org/bots/api#setbusinessaccountprofilephoto
 type SetBusinessAccountProfilePhoto struct {
 	BusinessConnectionID string            `json:"business_connection_id"`
@@ -239,6 +270,7 @@ type SetBusinessAccountProfilePhoto struct {
 }
 
 // SetBusinessAccountProfilePhoto sets the profile photo of a business account.
+// Since: Bot API 9.0
 // Returns true on success.
 // See https://core.telegram.org/bots/api#setbusinessaccountprofilephoto
 func (api *API) SetBusinessAccountProfilePhoto(params SetBusinessAccountProfilePhoto) (bool, error) {
@@ -247,6 +279,7 @@ func (api *API) SetBusinessAccountProfilePhoto(params SetBusinessAccountProfileP
 }
 
 // SetBusinessAccountProfilePhotoWithContext is the context-aware variant of SetBusinessAccountProfilePhoto.
+// Since: Bot API 9.0
 // It executes the same request but uses ctx for cancellation and deadlines.
 // See https://core.telegram.org/bots/api#setbusinessaccountprofilephoto
 func (api *API) SetBusinessAccountProfilePhotoWithContext(ctx context.Context, params SetBusinessAccountProfilePhoto) (bool, error) {
@@ -254,100 +287,113 @@ func (api *API) SetBusinessAccountProfilePhotoWithContext(ctx context.Context, p
 	return req.DoWithContext(ctx, api)
 }
 
-// RemoveBusinessAccountProfilePhotoP holds parameters for the removeBusinessAccountProfilePhoto method.
+// RemoveBusinessAccountProfilePhoto holds parameters for the removeBusinessAccountProfilePhoto method.
+// Since: Bot API 9.0
 // See https://core.telegram.org/bots/api#removebusinessaccountprofilephoto
-type RemoveBusinessAccountProfilePhotoP struct {
+type RemoveBusinessAccountProfilePhoto struct {
 	BusinessConnectionID string `json:"business_connection_id"`
 	IsPublic             bool   `json:"is_public,omitempty"`
 }
 
 // RemoveBusinessAccountProfilePhoto removes the profile photo of a business account.
+// Since: Bot API 9.0
 // Returns true on success.
 // See https://core.telegram.org/bots/api#removebusinessaccountprofilephoto
-func (api *API) RemoveBusinessAccountProfilePhoto(params RemoveBusinessAccountProfilePhotoP) (bool, error) {
+func (api *API) RemoveBusinessAccountProfilePhoto(params RemoveBusinessAccountProfilePhoto) (bool, error) {
 	req := NewRequest[bool]("removeBusinessAccountProfilePhoto", params)
 	return req.Do(api)
 }
 
 // RemoveBusinessAccountProfilePhotoWithContext is the context-aware variant of RemoveBusinessAccountProfilePhoto.
+// Since: Bot API 9.0
 // It executes the same request but uses ctx for cancellation and deadlines.
 // See https://core.telegram.org/bots/api#removebusinessaccountprofilephoto
-func (api *API) RemoveBusinessAccountProfilePhotoWithContext(ctx context.Context, params RemoveBusinessAccountProfilePhotoP) (bool, error) {
+func (api *API) RemoveBusinessAccountProfilePhotoWithContext(ctx context.Context, params RemoveBusinessAccountProfilePhoto) (bool, error) {
 	req := NewRequest[bool]("removeBusinessAccountProfilePhoto", params)
 	return req.DoWithContext(ctx, api)
 }
 
-// SetBusinessAccountGiftSettingsP holds parameters for the setBusinessAccountGiftSettings method.
+// SetBusinessAccountGiftSettings holds parameters for the setBusinessAccountGiftSettings method.
+// Since: Bot API 9.0
 // See https://core.telegram.org/bots/api#setbusinessaccountgiftsettings
-type SetBusinessAccountGiftSettingsP struct {
+type SetBusinessAccountGiftSettings struct {
 	BusinessConnectionID string            `json:"business_connection_id"`
 	ShowGiftButton       bool              `json:"show_gift_button"`
 	AcceptedGiftTypes    AcceptedGiftTypes `json:"accepted_gift_types"`
 }
 
 // SetBusinessAccountGiftSettings sets gift settings for a business account.
+// Since: Bot API 9.0
 // Returns true on success.
 // See https://core.telegram.org/bots/api#setbusinessaccountgiftsettings
-func (api *API) SetBusinessAccountGiftSettings(params SetBusinessAccountGiftSettingsP) (bool, error) {
+func (api *API) SetBusinessAccountGiftSettings(params SetBusinessAccountGiftSettings) (bool, error) {
 	req := NewRequest[bool]("setBusinessAccountGiftSettings", params)
 	return req.Do(api)
 }
 
 // SetBusinessAccountGiftSettingsWithContext is the context-aware variant of SetBusinessAccountGiftSettings.
+// Since: Bot API 9.0
 // It executes the same request but uses ctx for cancellation and deadlines.
 // See https://core.telegram.org/bots/api#setbusinessaccountgiftsettings
-func (api *API) SetBusinessAccountGiftSettingsWithContext(ctx context.Context, params SetBusinessAccountGiftSettingsP) (bool, error) {
+func (api *API) SetBusinessAccountGiftSettingsWithContext(ctx context.Context, params SetBusinessAccountGiftSettings) (bool, error) {
 	req := NewRequest[bool]("setBusinessAccountGiftSettings", params)
 	return req.DoWithContext(ctx, api)
 }
 
-// GetBusinessAccountStarBalanceP holds parameters for the getBusinessAccountStarBalance method.
+// GetBusinessAccountStarBalance holds parameters for the getBusinessAccountStarBalance method.
+// Since: Bot API 9.0
 // See https://core.telegram.org/bots/api#getbusinessaccountstarbalance
-type GetBusinessAccountStarBalanceP struct {
+type GetBusinessAccountStarBalance struct {
 	BusinessConnectionID string `json:"business_connection_id"`
 }
 
 // GetBusinessAccountStarBalance returns the star balance of a business account.
+// Since: Bot API 9.0
 // See https://core.telegram.org/bots/api#getbusinessaccountstarbalance
-func (api *API) GetBusinessAccountStarBalance(params GetBusinessAccountStarBalanceP) (StarAmount, error) {
+func (api *API) GetBusinessAccountStarBalance(params GetBusinessAccountStarBalance) (StarAmount, error) {
 	req := NewRequest[StarAmount]("getBusinessAccountStarBalance", params)
 	return req.Do(api)
 }
 
 // GetBusinessAccountStarBalanceWithContext is the context-aware variant of GetBusinessAccountStarBalance.
+// Since: Bot API 9.0
 // It executes the same request but uses ctx for cancellation and deadlines.
 // See https://core.telegram.org/bots/api#getbusinessaccountstarbalance
-func (api *API) GetBusinessAccountStarBalanceWithContext(ctx context.Context, params GetBusinessAccountStarBalanceP) (StarAmount, error) {
+func (api *API) GetBusinessAccountStarBalanceWithContext(ctx context.Context, params GetBusinessAccountStarBalance) (StarAmount, error) {
 	req := NewRequest[StarAmount]("getBusinessAccountStarBalance", params)
 	return req.DoWithContext(ctx, api)
 }
 
-// TransferBusinessAccountStarsP holds parameters for the transferBusinessAccountStars method.
+// TransferBusinessAccountStars holds parameters for the transferBusinessAccountStars method.
+// Since: Bot API 9.0
 // See https://core.telegram.org/bots/api#transferbusinessaccountstars
-type TransferBusinessAccountStarsP struct {
+type TransferBusinessAccountStars struct {
 	BusinessConnectionID string `json:"business_connection_id"`
 	StarCount            int    `json:"star_count"`
 }
 
 // TransferBusinessAccountStars transfers stars from a business account.
+// Since: Bot API 9.0
 // Returns true on success.
 // See https://core.telegram.org/bots/api#transferbusinessaccountstars
-func (api *API) TransferBusinessAccountStars(params TransferBusinessAccountStarsP) (bool, error) {
+func (api *API) TransferBusinessAccountStars(params TransferBusinessAccountStars) (bool, error) {
 	req := NewRequest[bool]("transferBusinessAccountStars", params)
 	return req.Do(api)
 }
 
 // TransferBusinessAccountStarsWithContext is the context-aware variant of TransferBusinessAccountStars.
+// Since: Bot API 9.0
 // It executes the same request but uses ctx for cancellation and deadlines.
 // See https://core.telegram.org/bots/api#transferbusinessaccountstars
-func (api *API) TransferBusinessAccountStarsWithContext(ctx context.Context, params TransferBusinessAccountStarsP) (bool, error) {
+func (api *API) TransferBusinessAccountStarsWithContext(ctx context.Context, params TransferBusinessAccountStars) (bool, error) {
 	req := NewRequest[bool]("transferBusinessAccountStars", params)
 	return req.DoWithContext(ctx, api)
 }
 
-// GetBusinessAccountGiftsP holds parameters for the getBusinessAccountGifts method.
+// GetBusinessAccountGifts holds parameters for the getBusinessAccountGifts method.
+// Since: Bot API 9.0
 // See https://core.telegram.org/bots/api#getbusinessaccountgifts
-type GetBusinessAccountGiftsP struct {
+type GetBusinessAccountGifts struct {
 	BusinessConnectionID        string `json:"business_connection_id"`
 	ExcludeUnsaved              bool   `json:"exclude_unsaved,omitempty"`
 	ExcludeSaved                bool   `json:"exclude_saved,omitempty"`
@@ -362,46 +408,52 @@ type GetBusinessAccountGiftsP struct {
 }
 
 // GetBusinessAccountGifts returns gifts owned by a business account.
+// Since: Bot API 9.0
 // See https://core.telegram.org/bots/api#getbusinessaccountgifts
-func (api *API) GetBusinessAccountGifts(params GetBusinessAccountGiftsP) (OwnedGifts, error) {
+func (api *API) GetBusinessAccountGifts(params GetBusinessAccountGifts) (OwnedGifts, error) {
 	req := NewRequest[OwnedGifts]("getBusinessAccountGifts", params)
 	return req.Do(api)
 }
 
 // GetBusinessAccountGiftsWithContext is the context-aware variant of GetBusinessAccountGifts.
+// Since: Bot API 9.0
 // It executes the same request but uses ctx for cancellation and deadlines.
 // See https://core.telegram.org/bots/api#getbusinessaccountgifts
-func (api *API) GetBusinessAccountGiftsWithContext(ctx context.Context, params GetBusinessAccountGiftsP) (OwnedGifts, error) {
+func (api *API) GetBusinessAccountGiftsWithContext(ctx context.Context, params GetBusinessAccountGifts) (OwnedGifts, error) {
 	req := NewRequest[OwnedGifts]("getBusinessAccountGifts", params)
 	return req.DoWithContext(ctx, api)
 }
 
-// ConvertGiftToStarsP holds parameters for the convertGiftToStars method.
+// ConvertGiftToStars holds parameters for the convertGiftToStars method.
+// Since: Bot API 9.0
 // See https://core.telegram.org/bots/api#convertgifttostars
-type ConvertGiftToStarsP struct {
+type ConvertGiftToStars struct {
 	BusinessConnectionID string `json:"business_connection_id"`
 	OwnedGiftID          string `json:"owned_gift_id"`
 }
 
 // ConvertGiftToStars converts a gift to Telegram Stars.
+// Since: Bot API 9.0
 // Returns true on success.
 // See https://core.telegram.org/bots/api#convertgifttostars
-func (api *API) ConvertGiftToStars(params ConvertGiftToStarsP) (bool, error) {
+func (api *API) ConvertGiftToStars(params ConvertGiftToStars) (bool, error) {
 	req := NewRequest[bool]("convertGiftToStars", params)
 	return req.Do(api)
 }
 
 // ConvertGiftToStarsWithContext is the context-aware variant of ConvertGiftToStars.
+// Since: Bot API 9.0
 // It executes the same request but uses ctx for cancellation and deadlines.
 // See https://core.telegram.org/bots/api#convertgifttostars
-func (api *API) ConvertGiftToStarsWithContext(ctx context.Context, params ConvertGiftToStarsP) (bool, error) {
+func (api *API) ConvertGiftToStarsWithContext(ctx context.Context, params ConvertGiftToStars) (bool, error) {
 	req := NewRequest[bool]("convertGiftToStars", params)
 	return req.DoWithContext(ctx, api)
 }
 
-// UpgradeGiftP holds parameters for the upgradeGift method.
+// UpgradeGift holds parameters for the upgradeGift method.
+// Since: Bot API 9.0
 // See https://core.telegram.org/bots/api#upgradegift
-type UpgradeGiftP struct {
+type UpgradeGift struct {
 	BusinessConnectionID string `json:"business_connection_id"`
 	OwnedGiftID          string `json:"owned_gift_id"`
 	KeepOriginalDetails  bool   `json:"keep_original_details,omitempty"`
@@ -409,24 +461,27 @@ type UpgradeGiftP struct {
 }
 
 // UpgradeGift upgrades a gift.
+// Since: Bot API 9.0
 // Returns true on success.
 // See https://core.telegram.org/bots/api#upgradegift
-func (api *API) UpgradeGift(params UpgradeGiftP) (bool, error) {
+func (api *API) UpgradeGift(params UpgradeGift) (bool, error) {
 	req := NewRequest[bool]("upgradeGift", params)
 	return req.Do(api)
 }
 
 // UpgradeGiftWithContext is the context-aware variant of UpgradeGift.
+// Since: Bot API 9.0
 // It executes the same request but uses ctx for cancellation and deadlines.
 // See https://core.telegram.org/bots/api#upgradegift
-func (api *API) UpgradeGiftWithContext(ctx context.Context, params UpgradeGiftP) (bool, error) {
+func (api *API) UpgradeGiftWithContext(ctx context.Context, params UpgradeGift) (bool, error) {
 	req := NewRequest[bool]("upgradeGift", params)
 	return req.DoWithContext(ctx, api)
 }
 
-// TransferGiftP holds parameters for the transferGift method.
+// TransferGift holds parameters for the transferGift method.
+// Since: Bot API 9.0
 // See https://core.telegram.org/bots/api#transfergift
-type TransferGiftP struct {
+type TransferGift struct {
 	BusinessConnectionID string `json:"business_connection_id"`
 	OwnedGiftID          string `json:"owned_gift_id"`
 	NewOwnerChatID       int64  `json:"new_owner_chat_id"`
@@ -434,24 +489,27 @@ type TransferGiftP struct {
 }
 
 // TransferGift transfers a gift to another chat.
+// Since: Bot API 9.0
 // Returns true on success.
 // See https://core.telegram.org/bots/api#transfergift
-func (api *API) TransferGift(params TransferGiftP) (bool, error) {
+func (api *API) TransferGift(params TransferGift) (bool, error) {
 	req := NewRequest[bool]("transferGift", params)
 	return req.Do(api)
 }
 
 // TransferGiftWithContext is the context-aware variant of TransferGift.
+// Since: Bot API 9.0
 // It executes the same request but uses ctx for cancellation and deadlines.
 // See https://core.telegram.org/bots/api#transfergift
-func (api *API) TransferGiftWithContext(ctx context.Context, params TransferGiftP) (bool, error) {
+func (api *API) TransferGiftWithContext(ctx context.Context, params TransferGift) (bool, error) {
 	req := NewRequest[bool]("transferGift", params)
 	return req.DoWithContext(ctx, api)
 }
 
-// PostStoryP holds parameters for the postStory method.
+// PostStory holds parameters for the postStory method.
+// Since: Bot API 7.2
 // See https://core.telegram.org/bots/api#poststory
-type PostStoryP struct {
+type PostStory struct {
 	BusinessConnectionID string            `json:"business_connection_id"`
 	Content              InputStoryContent `json:"content"`
 	ActivePeriod         int               `json:"active_period"`
@@ -465,39 +523,27 @@ type PostStoryP struct {
 	ProtectContent bool `json:"protect_content,omitempty"`
 }
 
-// PostStoryPhoto posts a story with a photo.
+// PostStory posts a story with a photo.
+// Since: Bot API 7.2
 // See https://core.telegram.org/bots/api#poststory
-func (api *API) PostStoryPhoto(params PostStoryP) (Story, error) {
+func (api *API) PostStory(params PostStory) (Story, error) {
 	req := NewRequest[Story]("postStory", params)
 	return req.Do(api)
 }
 
-// PostStoryPhotoWithContext is the context-aware variant of PostStoryPhoto.
+// PostStoryWithContext is the context-aware variant of PostStory.
+// Since: Bot API 7.2
 // It executes the same request but uses ctx for cancellation and deadlines.
 // See https://core.telegram.org/bots/api#poststory
-func (api *API) PostStoryPhotoWithContext(ctx context.Context, params PostStoryP) (Story, error) {
+func (api *API) PostStoryWithContext(ctx context.Context, params PostStory) (Story, error) {
 	req := NewRequest[Story]("postStory", params)
 	return req.DoWithContext(ctx, api)
 }
 
-// PostStoryVideo posts a story with a video.
+// RepostStory holds parameters for the repostStory method.
-// See https://core.telegram.org/bots/api#poststory
+// Since: Bot API 7.2
-func (api *API) PostStoryVideo(params PostStoryP) (Story, error) {
-	req := NewRequest[Story]("postStory", params)
-	return req.Do(api)
-}
-
-// PostStoryVideoWithContext is the context-aware variant of PostStoryVideo.
-// It executes the same request but uses ctx for cancellation and deadlines.
-// See https://core.telegram.org/bots/api#poststory
-func (api *API) PostStoryVideoWithContext(ctx context.Context, params PostStoryP) (Story, error) {
-	req := NewRequest[Story]("postStory", params)
-	return req.DoWithContext(ctx, api)
-}
-
-// RepostStoryP holds parameters for the repostStory method.
 // See https://core.telegram.org/bots/api#repoststory
-type RepostStoryP struct {
+type RepostStory struct {
 	BusinessConnectionID string `json:"business_connection_id"`
 	FromChatID           int64  `json:"from_chat_id"`
 	FromStoryID          int    `json:"from_story_id"`
@@ -507,24 +553,27 @@ type RepostStoryP struct {
 }
 
 // RepostStory reposts a story from another chat.
+// Since: Bot API 7.2
 // Returns the reposted story.
 // See https://core.telegram.org/bots/api#repoststory
-func (api *API) RepostStory(params RepostStoryP) (Story, error) {
+func (api *API) RepostStory(params RepostStory) (Story, error) {
 	req := NewRequest[Story]("repostStory", params)
 	return req.Do(api)
 }
 
 // RepostStoryWithContext is the context-aware variant of RepostStory.
+// Since: Bot API 7.2
 // It executes the same request but uses ctx for cancellation and deadlines.
 // See https://core.telegram.org/bots/api#repoststory
-func (api *API) RepostStoryWithContext(ctx context.Context, params RepostStoryP) (Story, error) {
+func (api *API) RepostStoryWithContext(ctx context.Context, params RepostStory) (Story, error) {
 	req := NewRequest[Story]("repostStory", params)
 	return req.DoWithContext(ctx, api)
 }
 
-// EditStoryP holds parameters for the editStory method.
+// EditStory holds parameters for the editStory method.
+// Since: Bot API 7.2
 // See https://core.telegram.org/bots/api#editstory
-type EditStoryP struct {
+type EditStory struct {
 	BusinessConnectionID string            `json:"business_connection_id"`
 	StoryID              int               `json:"story_id"`
 	Content              InputStoryContent `json:"content"`
@@ -536,40 +585,45 @@ type EditStoryP struct {
 }
 
 // EditStory edits an existing story.
+// Since: Bot API 7.2
 // Returns the updated story.
 // See https://core.telegram.org/bots/api#editstory
-func (api *API) EditStory(params EditStoryP) (Story, error) {
+func (api *API) EditStory(params EditStory) (Story, error) {
 	req := NewRequest[Story]("editStory", params)
 	return req.Do(api)
 }
 
 // EditStoryWithContext is the context-aware variant of EditStory.
+// Since: Bot API 7.2
 // It executes the same request but uses ctx for cancellation and deadlines.
 // See https://core.telegram.org/bots/api#editstory
-func (api *API) EditStoryWithContext(ctx context.Context, params EditStoryP) (Story, error) {
+func (api *API) EditStoryWithContext(ctx context.Context, params EditStory) (Story, error) {
 	req := NewRequest[Story]("editStory", params)
 	return req.DoWithContext(ctx, api)
 }
 
-// DeleteStoryP holds parameters for the deleteStory method.
+// DeleteStory holds parameters for the deleteStory method.
+// Since: Bot API 7.2
 // See https://core.telegram.org/bots/api#deletestory
-type DeleteStoryP struct {
+type DeleteStory struct {
 	BusinessConnectionID string `json:"business_connection_id"`
 	StoryID              int    `json:"story_id"`
 }
 
 // DeleteStory deletes a story.
+// Since: Bot API 7.2
 // Returns true on success.
 // See https://core.telegram.org/bots/api#deletestory
-func (api *API) DeleteStory(params DeleteStoryP) (bool, error) {
+func (api *API) DeleteStory(params DeleteStory) (bool, error) {
 	req := NewRequest[bool]("deleteStory", params)
 	return req.Do(api)
 }
 
 // DeleteStoryWithContext is the context-aware variant of DeleteStory.
+// Since: Bot API 7.2
 // It executes the same request but uses ctx for cancellation and deadlines.
 // See https://core.telegram.org/bots/api#deletestory
-func (api *API) DeleteStoryWithContext(ctx context.Context, params DeleteStoryP) (bool, error) {
+func (api *API) DeleteStoryWithContext(ctx context.Context, params DeleteStory) (bool, error) {
 	req := NewRequest[bool]("deleteStory", params)
 	return req.DoWithContext(ctx, api)
 }

tgapi/business_types.go

@@ -1,6 +1,7 @@
 package tgapi
 
 // BusinessIntro contains information about the business intro.
+// Since: Bot API 7.2
 // See https://core.telegram.org/bots/api#businessintro
 type BusinessIntro struct {
 	Title   string   `json:"title,omitempty"`
@@ -9,6 +10,7 @@ type BusinessIntro struct {
 }
 
 // BusinessLocation contains information about the business location.
+// Since: Bot API 7.2
 // See https://core.telegram.org/bots/api#businesslocation
 type BusinessLocation struct {
 	Address  string    `json:"address"`
@@ -16,6 +18,7 @@ type BusinessLocation struct {
 }
 
 // BusinessOpeningHoursInterval represents an interval of opening hours.
+// Since: Bot API 7.2
 // See https://core.telegram.org/bots/api#businessopeninghoursinterval
 type BusinessOpeningHoursInterval struct {
 	OpeningMinute int `json:"opening_minute"`
@@ -23,6 +26,7 @@ type BusinessOpeningHoursInterval struct {
 }
 
 // BusinessOpeningHours represents the opening hours of a business.
+// Since: Bot API 7.2
 // See https://core.telegram.org/bots/api#businessopeninghours
 type BusinessOpeningHours struct {
 	TimeZoneName string                         `json:"time_zone_name"`
@@ -31,6 +35,7 @@ type BusinessOpeningHours struct {
 
 // BusinessBotRights represents the rights of a business bot.
 // All fields are optional booleans that, when present, are always true.
+// Since: Bot API 9.0
 // See https://core.telegram.org/bots/api#businessbotrights
 type BusinessBotRights struct {
 	CanReply                   *bool `json:"can_reply,omitempty"`
@@ -50,6 +55,7 @@ type BusinessBotRights struct {
 }
 
 // BusinessConnection contains information about a business connection.
+// Since: Bot API 7.2
 // See https://core.telegram.org/bots/api#businessconnection
 type BusinessConnection struct {
 	ID         string             `json:"id"`
@@ -61,6 +67,7 @@ type BusinessConnection struct {
 }
 
 // BusinessMessagesDeleted is received when messages are deleted from a connected business account.
+// Since: Bot API 7.2
 // See https://core.telegram.org/bots/api#businessmessagesdeleted
 type BusinessMessagesDeleted struct {
 	BusinessConnectionID string `json:"business_connection_id"`
@@ -79,6 +86,7 @@ const (
 )
 
 // InputStoryContent represents the content of a story to be posted.
+// Since: Bot API 9.0
 // See https://core.telegram.org/bots/api#inputstorycontent
 type InputStoryContent struct {
 	Type InputStoryContentType `json:"type"`
@@ -94,6 +102,7 @@ type InputStoryContent struct {
 }
 
 // StoryAreaPosition describes the position of a clickable area on a story.
+// Since: Bot API 9.0
 // See https://core.telegram.org/bots/api#storyareaposition
 type StoryAreaPosition struct {
 	XPercentage            float64 `json:"x_percentage"`
@@ -121,7 +130,7 @@ const (
 )
 
 // StoryAreaType describes the type of a clickable area on a story.
-// Fields should be set according to the Type.
+// Since: Bot API 9.0
 // See https://core.telegram.org/bots/api#storyareatype
 type StoryAreaType struct {
 	Type StoryAreaTypeType `json:"type"`
@@ -149,6 +158,7 @@ type StoryAreaType struct {
 }
 
 // StoryArea represents a clickable area on a story.
+// Since: Bot API 9.0
 // See https://core.telegram.org/bots/api#storyarea
 type StoryArea struct {
 	Position StoryAreaPosition `json:"position"`

tgapi/chat_types.go

@@ -1,16 +1,17 @@
 package tgapi
 
 // Chat represents a chat (private, group, supergroup, channel).
+// Since: Bot API 1.0
 // See https://core.telegram.org/bots/api#chat
 type Chat struct {
-	ID               int64   `json:"id"`
+	ID               int64    `json:"id"`
-	Type             string  `json:"type"`
+	Type             ChatType `json:"type"`
-	Title            *string `json:"title,omitempty"`
+	Title            *string  `json:"title,omitempty"`
-	Username         *string `json:"username,omitempty"`
+	Username         *string  `json:"username,omitempty"`
-	FirstName        *string `json:"first_name,omitempty"`
+	FirstName        *string  `json:"first_name,omitempty"`
-	LastName         *string `json:"last_name,omitempty"`
+	LastName         *string  `json:"last_name,omitempty"`
-	IsForum          *bool   `json:"is_forum,omitempty"`
+	IsForum          *bool    `json:"is_forum,omitempty"`           // Since: Bot API 6.3
-	IsDirectMessages *bool   `json:"is_direct_messages,omitempty"`
+	IsDirectMessages *bool    `json:"is_direct_messages,omitempty"` // Since: Bot API 9.2
 }
 
 // ChatType represents the type of a chat.
@@ -28,6 +29,7 @@ const (
 )
 
 // ChatFullInfo contains full information about a chat.
+// Since: Bot API 7.5
 // See https://core.telegram.org/bots/api#chatfullinfo
 type ChatFullInfo struct {
 	ID               int64      `json:"id"`
@@ -49,7 +51,7 @@ type ChatFullInfo struct {
 	BusinessOpeningHours *BusinessOpeningHours `json:"business_opening_hours,omitempty"`
 
 	PersonalChat *Chat `json:"personal_chat,omitempty"`
-	ParentChat   *Chat `json:"parent_chat,omitempty"`
+	ParentChat   *Chat `json:"parent_chat,omitempty"` // Since: Bot API 9.2
 
 	AvailableReaction []ReactionType `json:"available_reaction,omitempty"`
 
@@ -86,12 +88,13 @@ type ChatFullInfo struct {
 
 	Location             *ChatLocation     `json:"location,omitempty"`
 	Rating               *UserRating       `json:"rating,omitempty"`
-	FirstProfileAudio    *Audio            `json:"first_profile_audio,omitempty"`
+	FirstProfileAudio    *Audio            `json:"first_profile_audio,omitempty"`     // Since: Bot API 9.4
-	UniqueGiftColors     *UniqueGiftColors `json:"unique_gift_colors,omitempty"`
+	UniqueGiftColors     *UniqueGiftColors `json:"unique_gift_colors,omitempty"`      // Since: Bot API 9.3
-	PaidMessageStarCount *int              `json:"paid_message_star_count,omitempty"`
+	PaidMessageStarCount *int              `json:"paid_message_star_count,omitempty"` // Since: Bot API 9.3
 }
 
 // ChatPhoto represents a chat photo.
+// Since: Bot API 3.1
 // See https://core.telegram.org/bots/api#chatphoto
 type ChatPhoto struct {
 	SmallFileID       string `json:"small_file_id"`
@@ -101,25 +104,29 @@ type ChatPhoto struct {
 }
 
 // ChatPermissions describes actions that a non‑administrator user is allowed to take in a chat.
+// Since: Bot API 4.4
 // See https://core.telegram.org/bots/api#chatpermissions
 type ChatPermissions struct {
 	CanSendMessages      bool `json:"can_send_messages"`
-	CanSendAudios        bool `json:"can_send_audios"`
+	CanSendAudios        bool `json:"can_send_audios"`      // Since: Bot API 6.5
-	CanSendDocuments     bool `json:"can_send_documents"`
+	CanSendDocuments     bool `json:"can_send_documents"`   // Since: Bot API 6.5
-	CanSendPhotos        bool `json:"can_send_photos"`
+	CanSendPhotos        bool `json:"can_send_photos"`      // Since: Bot API 6.5
-	CanSendVideoNotes    bool `json:"can_send_video_notes"`
+	CanSendVideos        bool `json:"can_send_videos"`      // Since: Bot API 6.5
-	CanSendVoiceNotes    bool `json:"can_send_voice_notes"`
+	CanSendVideoNotes    bool `json:"can_send_video_notes"` // Since: Bot API 6.5
+	CanSendVoiceNotes    bool `json:"can_send_voice_notes"` // Since: Bot API 6.5
 	CanSendPolls         bool `json:"can_send_polls"`
 	CanSendOtherMessages bool `json:"can_send_other_messages"`
-	CanAddWebPagePreview bool `json:"can_add_web_page_preview"`
+	CanAddWebPagePreview bool `json:"can_add_web_page_previews"`
-	CanEditTag           bool `json:"can_edit_tag"`
+	CanReactToMessages   bool `json:"can_react_to_messages"` // Since: Bot API 10.0
+	CanEditTag           bool `json:"can_edit_tag"`          // Since: Bot API 9.5
 	CanChangeInfo        bool `json:"can_change_info"`
 	CanInviteUsers       bool `json:"can_invite_users"`
 	CanPinMessages       bool `json:"can_pin_messages"`
-	CanManageTopics      bool `json:"can_manage_topics"`
+	CanManageTopics      bool `json:"can_manage_topics"` // Since: Bot API 6.3
 }
 
 // ChatLocation represents a location to which a chat is connected.
+// Since: Bot API 5.0
 // See https://core.telegram.org/bots/api#chatlocation
 type ChatLocation struct {
 	Location Location `json:"location"`
@@ -127,6 +134,7 @@ type ChatLocation struct {
 }
 
 // ChatInviteLink represents an invite link for a chat.
+// Since: Bot API 5.1
 // See https://core.telegram.org/bots/api#chatinvitelink
 type ChatInviteLink struct {
 	InviteLink        string `json:"invite_link"`
@@ -162,11 +170,12 @@ const (
 )
 
 // ChatMember contains information about one member of a chat.
+// Since: Bot API 3.1
 // See https://core.telegram.org/bots/api#chatmember
 type ChatMember struct {
 	Status ChatMemberStatusType `json:"status"`
 	User   User                 `json:"user"`
-	Tag    string               `json:"tag,omitempty"`
+	Tag    string               `json:"tag,omitempty"` // Since: Bot API 9.5
 
 	// Owner
 	IsAnonymous *bool   `json:"is_anonymous"`
@@ -181,16 +190,16 @@ type ChatMember struct {
 	CanPromoteMembers   *bool `json:"can_promote_members,omitempty"`
 	CanChangeInfo       *bool `json:"can_change_info,omitempty"`
 	CanInviteUsers      *bool `json:"can_invite_users,omitempty"`
-	CanPostStories      *bool `json:"can_post_stories,omitempty"`
+	CanPostStories      *bool `json:"can_post_stories,omitempty"`   // Since: Bot API 6.9
-	CanEditStories      *bool `json:"can_edit_stories,omitempty"`
+	CanEditStories      *bool `json:"can_edit_stories,omitempty"`   // Since: Bot API 6.9
-	CanDeleteStories    *bool `json:"can_delete_stories,omitempty"`
+	CanDeleteStories    *bool `json:"can_delete_stories,omitempty"` // Since: Bot API 6.9
 
 	CanPostMessages         *bool `json:"can_post_messages,omitempty"`
 	CanEditMessages         *bool `json:"can_edit_messages,omitempty"`
 	CanPinMessages          *bool `json:"can_pin_messages,omitempty"`
-	CanManageTopics         *bool `json:"can_manage_topics,omitempty"`
+	CanManageTopics         *bool `json:"can_manage_topics,omitempty"`          // Since: Bot API 6.3
-	CanManageDirectMessages *bool `json:"can_manage_direct_messages,omitempty"`
+	CanManageDirectMessages *bool `json:"can_manage_direct_messages,omitempty"` // Since: Bot API 9.1
-	CanManageTags           *bool `json:"can_manage_tags,omitempty"`
+	CanManageTags           *bool `json:"can_manage_tags,omitempty"`            // Since: Bot API 9.5
 
 	// Member
 	UntilDate *int `json:"until_date,omitempty"`
@@ -198,18 +207,21 @@ type ChatMember struct {
 	// Restricted
 	IsMember             *bool `json:"is_member,omitempty"`
 	CanSendMessages      *bool `json:"can_send_messages,omitempty"`
-	CanSendAudios        *bool `json:"can_send_audios,omitempty"`
+	CanSendAudios        *bool `json:"can_send_audios,omitempty"`      // Since: Bot API 6.5
-	CanSendDocuments     *bool `json:"can_send_documents,omitempty"`
+	CanSendDocuments     *bool `json:"can_send_documents,omitempty"`   // Since: Bot API 6.5
-	CanSendVideos        *bool `json:"can_send_videos,omitempty"`
+	CanSendPhotos        *bool `json:"can_send_photos,omitempty"`      // Since: Bot API 6.5
-	CanSendVideoNotes    *bool `json:"can_send_video_notes,omitempty"`
+	CanSendVideos        *bool `json:"can_send_videos,omitempty"`      // Since: Bot API 6.5
-	CanSendVoiceNotes    *bool `json:"can_send_voice_notes,omitempty"`
+	CanSendVideoNotes    *bool `json:"can_send_video_notes,omitempty"` // Since: Bot API 6.5
+	CanSendVoiceNotes    *bool `json:"can_send_voice_notes,omitempty"` // Since: Bot API 6.5
 	CanSendPolls         *bool `json:"can_send_polls,omitempty"`
 	CanSendOtherMessages *bool `json:"can_send_other_messages,omitempty"`
-	CanAddWebPagePreview *bool `json:"can_add_web_page_preview,omitempty"`
+	CanAddWebPagePreview *bool `json:"can_add_web_page_previews,omitempty"`
-	CanEditTag           *bool `json:"can_edit_tag,omitempty"`
+	CanReactToMessages   *bool `json:"can_react_to_messages,omitempty"` // Since: Bot API 10.0
+	CanEditTag           *bool `json:"can_edit_tag,omitempty"`          // Since: Bot API 9.5
 }
 
 // ChatBoostSource describes the source of a chat boost.
+// Since: Bot API 7.0
 // See https://core.telegram.org/bots/api#chatboostsource
 type ChatBoostSource struct {
 	Source string `json:"source"`
@@ -222,6 +234,7 @@ type ChatBoostSource struct {
 }
 
 // ChatBoost represents a boost added to a chat.
+// Since: Bot API 7.0
 // See https://core.telegram.org/bots/api#chatboost
 type ChatBoost struct {
 	BoostID        string          `json:"boost_id"`
@@ -231,12 +244,40 @@ type ChatBoost struct {
 }
 
 // UserChatBoosts represents a list of boosts a user has given to a chat.
+// Since: Bot API 7.0
 // See https://core.telegram.org/bots/api#userchatboosts
 type UserChatBoosts struct {
 	Boosts []ChatBoost `json:"boosts"`
 }
 
+// ChatBoostAdded describes a service message about a user boosting a chat.
+// Since: Bot API 7.1
+type ChatBoostAdded struct {
+	BoostCount int `json:"boost_count"`
+}
+
+// ChatBackground represents a chat background.
+// Since: Bot API 7.5
+type ChatBackground struct {
+	Type BackgroundType `json:"type"`
+}
+
+// ChatOwnerLeft describes a service message about a chat owner leaving.
+// Since: Bot API 9.4
+// See https://core.telegram.org/bots/api#chatownerleft
+type ChatOwnerLeft struct {
+	NewOwner *User `json:"new_owner,omitempty"`
+}
+
+// ChatOwnerChanged describes a service message about a chat owner change.
+// Since: Bot API 9.4
+// See https://core.telegram.org/bots/api#chatownerchanged
+type ChatOwnerChanged struct {
+	NewOwner User `json:"new_owner"`
+}
+
 // ChatAdministratorRights represents the rights of an administrator in a chat.
+// Since: Bot API 6.0
 // See https://core.telegram.org/bots/api#chatadministratorrights
 type ChatAdministratorRights struct {
 	IsAnonymous         bool `json:"is_anonymous"`
@@ -260,6 +301,7 @@ type ChatAdministratorRights struct {
 }
 
 // ChatBoostUpdated represents a boost added to a chat or changed.
+// Since: Bot API 7.0
 // See https://core.telegram.org/bots/api#chatboostupdated
 type ChatBoostUpdated struct {
 	Chat  Chat      `json:"chat"`
@@ -267,6 +309,7 @@ type ChatBoostUpdated struct {
 }
 
 // ChatBoostRemoved represents a boost removed from a chat.
+// Since: Bot API 7.0
 // See https://core.telegram.org/bots/api#chatboostremoved
 type ChatBoostRemoved struct {
 	Chat       Chat            `json:"chat"`

tgapi/errors.go

@@ -1,9 +1,9 @@
 package tgapi
 
-import "errors"
+import (
-
+	"errors"
-// ErrRateLimit reports that a request exceeded the configured rate limiter.
+	"fmt"
-var ErrRateLimit = errors.New("rate limit exceeded")
+)
 
 // ErrPoolUnexpected reports an unexpected result type returned from the worker pool.
 var ErrPoolUnexpected = errors.New("unexpected response from pool")
@@ -13,3 +13,18 @@ var ErrPoolQueueFull = errors.New("worker pool queue full")
 
 // ErrPoolStopped reports that a request was submitted after the worker pool stopped.
 var ErrPoolStopped = errors.New("worker pool stopped")
+
+// ResponseError reports an unsuccessful Telegram API response.
+type ResponseError struct {
+	Code        int
+	Description string
+	Parameters  *ResponseParameters
+}
+
+// Error returns the Telegram API error code and description.
+func (e *ResponseError) Error() string {
+	if e == nil {
+		return "<nil>"
+	}
+	return fmt.Sprintf("[%d] %s", e.Code, e.Description)
+}

tgapi/forum_methods.go

@@ -2,13 +2,15 @@ package tgapi
 
 import "context"
 
-// BaseForumTopicP contains common fields for forum topic operations that require a chat ID and a message thread ID.
+// BaseForumTopic contains common fields for forum topic operations that require a chat ID and a message thread ID.
-type BaseForumTopicP struct {
+// Since: Bot API 6.3
+type BaseForumTopic struct {
 	ChatID          int64 `json:"chat_id"`
 	MessageThreadID int   `json:"message_thread_id"`
 }
 
 // GetForumTopicIconStickers returns the list of custom emoji that can be used as a forum topic icon.
+// Since: Bot API 6.3
 // See https://core.telegram.org/bots/api#getforumtopiciconstickers
 func (api *API) GetForumTopicIconStickers() ([]Sticker, error) {
 	req := NewRequest[[]Sticker]("getForumTopicIconStickers", NoParams)
@@ -16,6 +18,7 @@ func (api *API) GetForumTopicIconStickers() ([]Sticker, error) {
 }
 
 // GetForumTopicIconStickersWithContext is the context-aware variant of GetForumTopicIconStickers.
+// Since: Bot API 6.3
 // It executes the same request but uses ctx for cancellation and deadlines.
 // See https://core.telegram.org/bots/api#getforumtopiciconstickers
 func (api *API) GetForumTopicIconStickersWithContext(ctx context.Context) ([]Sticker, error) {
@@ -23,9 +26,10 @@ func (api *API) GetForumTopicIconStickersWithContext(ctx context.Context) ([]Sti
 	return req.DoWithContext(ctx, api)
 }
 
-// CreateForumTopicP holds parameters for the createForumTopic method.
+// CreateForumTopic holds parameters for the createForumTopic method.
+// Since: Bot API 6.3
 // See https://core.telegram.org/bots/api#createforumtopic
-type CreateForumTopicP struct {
+type CreateForumTopic struct {
 	ChatID            int64               `json:"chat_id"`
 	Name              string              `json:"name"`
 	IconColor         ForumTopicIconColor `json:"icon_color"`
@@ -33,213 +37,240 @@ type CreateForumTopicP struct {
 }
 
 // CreateForumTopic creates a topic in a forum supergroup.
+// Since: Bot API 6.3
 // Returns the created ForumTopic on success.
 // See https://core.telegram.org/bots/api#createforumtopic
-func (api *API) CreateForumTopic(params CreateForumTopicP) (ForumTopic, error) {
+func (api *API) CreateForumTopic(params CreateForumTopic) (ForumTopic, error) {
 	req := NewRequestWithChatID[ForumTopic]("createForumTopic", params, params.ChatID)
 	return req.Do(api)
 }
 
 // CreateForumTopicWithContext is the context-aware variant of CreateForumTopic.
+// Since: Bot API 6.3
 // It executes the same request but uses ctx for cancellation and deadlines.
 // See https://core.telegram.org/bots/api#createforumtopic
-func (api *API) CreateForumTopicWithContext(ctx context.Context, params CreateForumTopicP) (ForumTopic, error) {
+func (api *API) CreateForumTopicWithContext(ctx context.Context, params CreateForumTopic) (ForumTopic, error) {
 	req := NewRequestWithChatID[ForumTopic]("createForumTopic", params, params.ChatID)
 	return req.DoWithContext(ctx, api)
 }
 
-// EditForumTopicP holds parameters for the editForumTopic method.
+// EditForumTopic holds parameters for the editForumTopic method.
+// Since: Bot API 6.3
 // See https://core.telegram.org/bots/api#editforumtopic
-type EditForumTopicP struct {
+type EditForumTopic struct {
-	BaseForumTopicP
+	BaseForumTopic
 	Name              string `json:"name"`
 	IconCustomEmojiID string `json:"icon_custom_emoji_id"`
 }
 
 // EditForumTopic edits name and icon of a forum topic.
+// Since: Bot API 6.3
 // Returns True on success.
 // See https://core.telegram.org/bots/api#editforumtopic
-func (api *API) EditForumTopic(params EditForumTopicP) (bool, error) {
+func (api *API) EditForumTopic(params EditForumTopic) (bool, error) {
 	req := NewRequestWithChatID[bool]("editForumTopic", params, params.ChatID)
 	return req.Do(api)
 }
 
 // EditForumTopicWithContext is the context-aware variant of EditForumTopic.
+// Since: Bot API 6.3
 // It executes the same request but uses ctx for cancellation and deadlines.
 // See https://core.telegram.org/bots/api#editforumtopic
-func (api *API) EditForumTopicWithContext(ctx context.Context, params EditForumTopicP) (bool, error) {
+func (api *API) EditForumTopicWithContext(ctx context.Context, params EditForumTopic) (bool, error) {
 	req := NewRequestWithChatID[bool]("editForumTopic", params, params.ChatID)
 	return req.DoWithContext(ctx, api)
 }
 
 // CloseForumTopic closes an open forum topic.
+// Since: Bot API 6.3
 // Returns True on success.
 // See https://core.telegram.org/bots/api#closeforumtopic
-func (api *API) CloseForumTopic(params BaseForumTopicP) (bool, error) {
+func (api *API) CloseForumTopic(params BaseForumTopic) (bool, error) {
 	req := NewRequestWithChatID[bool]("closeForumTopic", params, params.ChatID)
 	return req.Do(api)
 }
 
 // CloseForumTopicWithContext is the context-aware variant of CloseForumTopic.
+// Since: Bot API 6.3
 // It executes the same request but uses ctx for cancellation and deadlines.
 // See https://core.telegram.org/bots/api#closeforumtopic
-func (api *API) CloseForumTopicWithContext(ctx context.Context, params BaseForumTopicP) (bool, error) {
+func (api *API) CloseForumTopicWithContext(ctx context.Context, params BaseForumTopic) (bool, error) {
 	req := NewRequestWithChatID[bool]("closeForumTopic", params, params.ChatID)
 	return req.DoWithContext(ctx, api)
 }
 
 // ReopenForumTopic reopens a closed forum topic.
+// Since: Bot API 6.3
 // Returns True on success.
 // See https://core.telegram.org/bots/api#reopenforumtopic
-func (api *API) ReopenForumTopic(params BaseForumTopicP) (bool, error) {
+func (api *API) ReopenForumTopic(params BaseForumTopic) (bool, error) {
 	req := NewRequestWithChatID[bool]("reopenForumTopic", params, params.ChatID)
 	return req.Do(api)
 }
 
 // ReopenForumTopicWithContext is the context-aware variant of ReopenForumTopic.
+// Since: Bot API 6.3
 // It executes the same request but uses ctx for cancellation and deadlines.
 // See https://core.telegram.org/bots/api#reopenforumtopic
-func (api *API) ReopenForumTopicWithContext(ctx context.Context, params BaseForumTopicP) (bool, error) {
+func (api *API) ReopenForumTopicWithContext(ctx context.Context, params BaseForumTopic) (bool, error) {
 	req := NewRequestWithChatID[bool]("reopenForumTopic", params, params.ChatID)
 	return req.DoWithContext(ctx, api)
 }
 
 // DeleteForumTopic deletes a forum topic.
+// Since: Bot API 6.3
 // Returns True on success.
 // See https://core.telegram.org/bots/api#deleteforumtopic
-func (api *API) DeleteForumTopic(params BaseForumTopicP) (bool, error) {
+func (api *API) DeleteForumTopic(params BaseForumTopic) (bool, error) {
 	req := NewRequestWithChatID[bool]("deleteForumTopic", params, params.ChatID)
 	return req.Do(api)
 }
 
 // DeleteForumTopicWithContext is the context-aware variant of DeleteForumTopic.
+// Since: Bot API 6.3
 // It executes the same request but uses ctx for cancellation and deadlines.
 // See https://core.telegram.org/bots/api#deleteforumtopic
-func (api *API) DeleteForumTopicWithContext(ctx context.Context, params BaseForumTopicP) (bool, error) {
+func (api *API) DeleteForumTopicWithContext(ctx context.Context, params BaseForumTopic) (bool, error) {
 	req := NewRequestWithChatID[bool]("deleteForumTopic", params, params.ChatID)
 	return req.DoWithContext(ctx, api)
 }
 
 // UnpinAllForumTopicMessages clears the list of pinned messages in a forum topic.
+// Since: Bot API 6.3
 // Returns True on success.
 // See https://core.telegram.org/bots/api#unpinallforumtopicmessages
-func (api *API) UnpinAllForumTopicMessages(params BaseForumTopicP) (bool, error) {
+func (api *API) UnpinAllForumTopicMessages(params BaseForumTopic) (bool, error) {
 	req := NewRequestWithChatID[bool]("unpinAllForumTopicMessages", params, params.ChatID)
 	return req.Do(api)
 }
 
 // UnpinAllForumTopicMessagesWithContext is the context-aware variant of UnpinAllForumTopicMessages.
+// Since: Bot API 6.3
 // It executes the same request but uses ctx for cancellation and deadlines.
 // See https://core.telegram.org/bots/api#unpinallforumtopicmessages
-func (api *API) UnpinAllForumTopicMessagesWithContext(ctx context.Context, params BaseForumTopicP) (bool, error) {
+func (api *API) UnpinAllForumTopicMessagesWithContext(ctx context.Context, params BaseForumTopic) (bool, error) {
 	req := NewRequestWithChatID[bool]("unpinAllForumTopicMessages", params, params.ChatID)
 	return req.DoWithContext(ctx, api)
 }
 
-// BaseGeneralForumTopicP contains common fields for general forum topic operations that require a chat ID.
+// BaseGeneralForumTopic contains common fields for general forum topic operations that require a chat ID.
-type BaseGeneralForumTopicP struct {
+// Since: Bot API 6.4
+type BaseGeneralForumTopic struct {
 	ChatID int64 `json:"chat_id"`
 }
 
-// EditGeneralForumTopicP holds parameters for the editGeneralForumTopic method.
+// EditGeneralForumTopic holds parameters for the editGeneralForumTopic method.
+// Since: Bot API 6.4
 // See https://core.telegram.org/bots/api#editgeneralforumtopic
-type EditGeneralForumTopicP struct {
+type EditGeneralForumTopic struct {
 	ChatID int64  `json:"chat_id"`
 	Name   string `json:"name"`
 }
 
 // EditGeneralForumTopic edits the name of the 'General' topic in a forum supergroup.
+// Since: Bot API 6.4
 // Returns True on success.
 // See https://core.telegram.org/bots/api#editgeneralforumtopic
-func (api *API) EditGeneralForumTopic(params EditGeneralForumTopicP) (bool, error) {
+func (api *API) EditGeneralForumTopic(params EditGeneralForumTopic) (bool, error) {
 	req := NewRequestWithChatID[bool]("editGeneralForumTopic", params, params.ChatID)
 	return req.Do(api)
 }
 
 // EditGeneralForumTopicWithContext is the context-aware variant of EditGeneralForumTopic.
+// Since: Bot API 6.4
 // It executes the same request but uses ctx for cancellation and deadlines.
 // See https://core.telegram.org/bots/api#editgeneralforumtopic
-func (api *API) EditGeneralForumTopicWithContext(ctx context.Context, params EditGeneralForumTopicP) (bool, error) {
+func (api *API) EditGeneralForumTopicWithContext(ctx context.Context, params EditGeneralForumTopic) (bool, error) {
 	req := NewRequestWithChatID[bool]("editGeneralForumTopic", params, params.ChatID)
 	return req.DoWithContext(ctx, api)
 }
 
 // CloseGeneralForumTopic closes the 'General' topic in a forum supergroup.
+// Since: Bot API 6.4
 // Returns True on success.
 // See https://core.telegram.org/bots/api#closegeneralforumtopic
-func (api *API) CloseGeneralForumTopic(params BaseGeneralForumTopicP) (bool, error) {
+func (api *API) CloseGeneralForumTopic(params BaseGeneralForumTopic) (bool, error) {
 	req := NewRequestWithChatID[bool]("closeGeneralForumTopic", params, params.ChatID)
 	return req.Do(api)
 }
 
 // CloseGeneralForumTopicWithContext is the context-aware variant of CloseGeneralForumTopic.
+// Since: Bot API 6.4
 // It executes the same request but uses ctx for cancellation and deadlines.
 // See https://core.telegram.org/bots/api#closegeneralforumtopic
-func (api *API) CloseGeneralForumTopicWithContext(ctx context.Context, params BaseGeneralForumTopicP) (bool, error) {
+func (api *API) CloseGeneralForumTopicWithContext(ctx context.Context, params BaseGeneralForumTopic) (bool, error) {
 	req := NewRequestWithChatID[bool]("closeGeneralForumTopic", params, params.ChatID)
 	return req.DoWithContext(ctx, api)
 }
 
 // ReopenGeneralForumTopic reopens the 'General' topic in a forum supergroup.
+// Since: Bot API 6.4
 // Returns True on success.
 // See https://core.telegram.org/bots/api#reopengeneralforumtopic
-func (api *API) ReopenGeneralForumTopic(params BaseGeneralForumTopicP) (bool, error) {
+func (api *API) ReopenGeneralForumTopic(params BaseGeneralForumTopic) (bool, error) {
 	req := NewRequestWithChatID[bool]("reopenGeneralForumTopic", params, params.ChatID)
 	return req.Do(api)
 }
 
 // ReopenGeneralForumTopicWithContext is the context-aware variant of ReopenGeneralForumTopic.
+// Since: Bot API 6.4
 // It executes the same request but uses ctx for cancellation and deadlines.
 // See https://core.telegram.org/bots/api#reopengeneralforumtopic
-func (api *API) ReopenGeneralForumTopicWithContext(ctx context.Context, params BaseGeneralForumTopicP) (bool, error) {
+func (api *API) ReopenGeneralForumTopicWithContext(ctx context.Context, params BaseGeneralForumTopic) (bool, error) {
 	req := NewRequestWithChatID[bool]("reopenGeneralForumTopic", params, params.ChatID)
 	return req.DoWithContext(ctx, api)
 }
 
 // HideGeneralForumTopic hides the 'General' topic in a forum supergroup.
+// Since: Bot API 6.4
 // Returns True on success.
 // See https://core.telegram.org/bots/api#hidegeneralforumtopic
-func (api *API) HideGeneralForumTopic(params BaseGeneralForumTopicP) (bool, error) {
+func (api *API) HideGeneralForumTopic(params BaseGeneralForumTopic) (bool, error) {
 	req := NewRequestWithChatID[bool]("hideGeneralForumTopic", params, params.ChatID)
 	return req.Do(api)
 }
 
 // HideGeneralForumTopicWithContext is the context-aware variant of HideGeneralForumTopic.
+// Since: Bot API 6.4
 // It executes the same request but uses ctx for cancellation and deadlines.
 // See https://core.telegram.org/bots/api#hidegeneralforumtopic
-func (api *API) HideGeneralForumTopicWithContext(ctx context.Context, params BaseGeneralForumTopicP) (bool, error) {
+func (api *API) HideGeneralForumTopicWithContext(ctx context.Context, params BaseGeneralForumTopic) (bool, error) {
 	req := NewRequestWithChatID[bool]("hideGeneralForumTopic", params, params.ChatID)
 	return req.DoWithContext(ctx, api)
 }
 
 // UnhideGeneralForumTopic unhides the 'General' topic in a forum supergroup.
+// Since: Bot API 6.4
 // Returns True on success.
 // See https://core.telegram.org/bots/api#unhidegeneralforumtopic
-func (api *API) UnhideGeneralForumTopic(params BaseGeneralForumTopicP) (bool, error) {
+func (api *API) UnhideGeneralForumTopic(params BaseGeneralForumTopic) (bool, error) {
 	req := NewRequestWithChatID[bool]("unhideGeneralForumTopic", params, params.ChatID)
 	return req.Do(api)
 }
 
 // UnhideGeneralForumTopicWithContext is the context-aware variant of UnhideGeneralForumTopic.
+// Since: Bot API 6.4
 // It executes the same request but uses ctx for cancellation and deadlines.
 // See https://core.telegram.org/bots/api#unhidegeneralforumtopic
-func (api *API) UnhideGeneralForumTopicWithContext(ctx context.Context, params BaseGeneralForumTopicP) (bool, error) {
+func (api *API) UnhideGeneralForumTopicWithContext(ctx context.Context, params BaseGeneralForumTopic) (bool, error) {
 	req := NewRequestWithChatID[bool]("unhideGeneralForumTopic", params, params.ChatID)
 	return req.DoWithContext(ctx, api)
 }
 
 // UnpinAllGeneralForumTopicMessages clears the list of pinned messages in the 'General' topic.
+// Since: Bot API 6.4
 // Returns True on success.
 // See https://core.telegram.org/bots/api#unpinallgeneralforumtopicmessages
-func (api *API) UnpinAllGeneralForumTopicMessages(params BaseGeneralForumTopicP) (bool, error) {
+func (api *API) UnpinAllGeneralForumTopicMessages(params BaseGeneralForumTopic) (bool, error) {
 	req := NewRequestWithChatID[bool]("unpinAllGeneralForumTopicMessages", params, params.ChatID)
 	return req.Do(api)
 }
 
 // UnpinAllGeneralForumTopicMessagesWithContext is the context-aware variant of UnpinAllGeneralForumTopicMessages.
+// Since: Bot API 6.4
 // It executes the same request but uses ctx for cancellation and deadlines.
 // See https://core.telegram.org/bots/api#unpinallgeneralforumtopicmessages
-func (api *API) UnpinAllGeneralForumTopicMessagesWithContext(ctx context.Context, params BaseGeneralForumTopicP) (bool, error) {
+func (api *API) UnpinAllGeneralForumTopicMessagesWithContext(ctx context.Context, params BaseGeneralForumTopic) (bool, error) {
 	req := NewRequestWithChatID[bool]("unpinAllGeneralForumTopicMessages", params, params.ChatID)
 	return req.DoWithContext(ctx, api)
 }

tgapi/forum_types.go

@@ -1,6 +1,7 @@
 package tgapi
 
 // ForumTopic represents a forum topic.
+// Since: Bot API 6.3
 // See https://core.telegram.org/bots/api#forumtopic
 type ForumTopic struct {
 	MessageThreadID   int    `json:"message_thread_id"`
@@ -12,6 +13,7 @@ type ForumTopic struct {
 
 // ForumTopicIconColor represents the color of a forum topic icon.
 // The value is an integer representing the color in RGB format.
+// Since: Bot API 6.3
 // See https://core.telegram.org/bots/api#forumtopiciconcolor
 type ForumTopicIconColor int
 
@@ -19,3 +21,35 @@ const (
 	// ForumTopicIconColorBlue is the blue color for forum topic icons (value 7322096).
 	ForumTopicIconColorBlue ForumTopicIconColor = 7322096
 )
+
+// ForumTopicCreated represents a service message about a new forum topic created.
+// Since: Bot API 6.3
+type ForumTopicCreated struct {
+	Name              string `json:"name"`
+	IconColor         int    `json:"icon_color"`
+	IconCustomEmojiID string `json:"icon_custom_emoji_id,omitempty"`
+	IsNameImplicit    bool   `json:"is_name_implicit,omitempty"`
+}
+
+// ForumTopicEdited represents a service message about an edited forum topic.
+// Since: Bot API 6.4
+type ForumTopicEdited struct {
+	Name              string `json:"name,omitempty"`
+	IconCustomEmojiID string `json:"icon_custom_emoji_id,omitempty"`
+}
+
+// ForumTopicClosed represents a service message about a forum topic closed.
+// Since: Bot API 6.3
+type ForumTopicClosed struct{}
+
+// ForumTopicReopened represents a service message about a forum topic reopened.
+// Since: Bot API 6.3
+type ForumTopicReopened struct{}
+
+// GeneralForumTopicHidden represents a service message about the General forum topic hidden.
+// Since: Bot API 6.4
+type GeneralForumTopicHidden struct{}
+
+// GeneralForumTopicUnhidden represents a service message about the General forum topic unhidden.
+// Since: Bot API 6.4
+type GeneralForumTopicUnhidden struct{}

tgapi/games_methods.go

@@ -2,9 +2,10 @@ package tgapi
 
 import "context"
 
-// SendGameP holds parameters for the sendGame method.
+// SendGame holds parameters for the sendGame method.
+// Since: Bot API 2.2
 // See https://core.telegram.org/bots/api#sendgame
-type SendGameP struct {
+type SendGame struct {
 	BusinessConnectionID string `json:"business_connection_id,omitempty"`
 	ChatID               int64  `json:"chat_id"`
 	MessageThreadID      int    `json:"message_thread_id,omitempty"`
@@ -20,23 +21,26 @@ type SendGameP struct {
 }
 
 // SendGame sends a game message.
+// Since: Bot API 2.2
 // See https://core.telegram.org/bots/api#sendgame
-func (api *API) SendGame(params SendGameP) (Message, error) {
+func (api *API) SendGame(params SendGame) (Message, error) {
 	req := NewRequestWithChatID[Message]("sendGame", params, params.ChatID)
 	return req.Do(api)
 }
 
 // SendGameWithContext is the context-aware variant of SendGame.
+// Since: Bot API 2.2
 // It executes the same request but uses ctx for cancellation and deadlines.
 // See https://core.telegram.org/bots/api#sendgame
-func (api *API) SendGameWithContext(ctx context.Context, params SendGameP) (Message, error) {
+func (api *API) SendGameWithContext(ctx context.Context, params SendGame) (Message, error) {
 	req := NewRequestWithChatID[Message]("sendGame", params, params.ChatID)
 	return req.DoWithContext(ctx, api)
 }
 
-// SetGameScoreP holds parameters for the setGameScore method.
+// SetGameScore holds parameters for the setGameScore method.
+// Since: Bot API 2.2
 // See https://core.telegram.org/bots/api#setgamescore
-type SetGameScoreP struct {
+type SetGameScore struct {
 	UserID             int64  `json:"user_id"`
 	Score              int    `json:"score"`
 	Force              bool   `json:"force,omitempty"`
@@ -47,10 +51,11 @@ type SetGameScoreP struct {
 }
 
 // SetGameScore sets a user's score in a game message.
+// Since: Bot API 2.2
 // If inline_message_id is provided, returns a boolean success flag.
 // Otherwise returns the edited Message.
 // See https://core.telegram.org/bots/api#setgamescore
-func (api *API) SetGameScore(params SetGameScoreP) (Message, bool, error) {
+func (api *API) SetGameScore(params SetGameScore) (Message, bool, error) {
 	var zero Message
 	if params.InlineMessageID != "" {
 		req := NewRequestWithChatID[bool]("setGameScore", params, params.ChatID)
@@ -63,9 +68,10 @@ func (api *API) SetGameScore(params SetGameScoreP) (Message, bool, error) {
 }
 
 // SetGameScoreWithContext is the context-aware variant of SetGameScore.
+// Since: Bot API 2.2
 // It executes the same request but uses ctx for cancellation and deadlines.
 // See https://core.telegram.org/bots/api#setgamescore
-func (api *API) SetGameScoreWithContext(ctx context.Context, params SetGameScoreP) (Message, bool, error) {
+func (api *API) SetGameScoreWithContext(ctx context.Context, params SetGameScore) (Message, bool, error) {
 	var zero Message
 	if params.InlineMessageID != "" {
 		req := NewRequestWithChatID[bool]("setGameScore", params, params.ChatID)
@@ -77,9 +83,10 @@ func (api *API) SetGameScoreWithContext(ctx context.Context, params SetGameScore
 	return res, false, err
 }
 
-// GetGameHighScoresP holds parameters for the getGameHighScores method.
+// GetGameHighScores holds parameters for the getGameHighScores method.
+// Since: Bot API 2.2
 // See https://core.telegram.org/bots/api#getgamehighscores
-type GetGameHighScoresP struct {
+type GetGameHighScores struct {
 	UserID          int64  `json:"user_id"`
 	ChatID          int64  `json:"chat_id,omitempty"`
 	MessageID       int    `json:"message_id,omitempty"`
@@ -87,16 +94,18 @@ type GetGameHighScoresP struct {
 }
 
 // GetGameHighScores returns game high score data for a user.
+// Since: Bot API 2.2
 // See https://core.telegram.org/bots/api#getgamehighscores
-func (api *API) GetGameHighScores(params GetGameHighScoresP) ([]GameHighScore, error) {
+func (api *API) GetGameHighScores(params GetGameHighScores) ([]GameHighScore, error) {
 	req := NewRequestWithChatID[[]GameHighScore]("getGameHighScores", params, params.ChatID)
 	return req.Do(api)
 }
 
 // GetGameHighScoresWithContext is the context-aware variant of GetGameHighScores.
+// Since: Bot API 2.2
 // It executes the same request but uses ctx for cancellation and deadlines.
 // See https://core.telegram.org/bots/api#getgamehighscores
-func (api *API) GetGameHighScoresWithContext(ctx context.Context, params GetGameHighScoresP) ([]GameHighScore, error) {
+func (api *API) GetGameHighScoresWithContext(ctx context.Context, params GetGameHighScores) ([]GameHighScore, error) {
 	req := NewRequestWithChatID[[]GameHighScore]("getGameHighScores", params, params.ChatID)
 	return req.DoWithContext(ctx, api)
 }

tgapi/games_types.go

@@ -1,6 +1,22 @@
 package tgapi
 
+// Game represents a game.
+// Since: Bot API 2.2
+type Game struct {
+	Title        string          `json:"title"`
+	Description  string          `json:"description"`
+	Photo        []PhotoSize     `json:"photo"`
+	Text         string          `json:"text,omitempty"`
+	TextEntities []MessageEntity `json:"text_entities,omitempty"`
+	Animation    *Animation      `json:"animation,omitempty"`
+}
+
+// CallbackGame is a placeholder for the future use of callback games.
+// Since: Bot API 2.2
+type CallbackGame struct{}
+
 // GameHighScore represents one row in a game high score table.
+// Since: Bot API 2.2
 // See https://core.telegram.org/bots/api#gamehighscore
 type GameHighScore struct {
 	Position int  `json:"position"`

tgapi/inline_methods.go

@@ -2,9 +2,10 @@ package tgapi
 
 import "context"
 
-// AnswerInlineQueryP holds parameters for the answerInlineQuery method.
+// AnswerInlineQuery holds parameters for the answerInlineQuery method.
+// Since: Bot API 1.7
 // See https://core.telegram.org/bots/api#answerinlinequery
-type AnswerInlineQueryP struct {
+type AnswerInlineQuery struct {
 	InlineQueryID string                    `json:"inline_query_id"`
 	Results       []InlineQueryResult       `json:"results"`
 	CacheTime     int                       `json:"cache_time,omitempty"`
@@ -14,46 +15,52 @@ type AnswerInlineQueryP struct {
 }
 
 // AnswerInlineQuery sends answers to an inline query.
+// Since: Bot API 1.7
 // Returns true on success.
 // See https://core.telegram.org/bots/api#answerinlinequery
-func (api *API) AnswerInlineQuery(params AnswerInlineQueryP) (bool, error) {
+func (api *API) AnswerInlineQuery(params AnswerInlineQuery) (bool, error) {
 	req := NewRequest[bool]("answerInlineQuery", params)
 	return req.Do(api)
 }
 
 // AnswerInlineQueryWithContext is the context-aware variant of AnswerInlineQuery.
+// Since: Bot API 1.7
 // It executes the same request but uses ctx for cancellation and deadlines.
 // See https://core.telegram.org/bots/api#answerinlinequery
-func (api *API) AnswerInlineQueryWithContext(ctx context.Context, params AnswerInlineQueryP) (bool, error) {
+func (api *API) AnswerInlineQueryWithContext(ctx context.Context, params AnswerInlineQuery) (bool, error) {
 	req := NewRequest[bool]("answerInlineQuery", params)
 	return req.DoWithContext(ctx, api)
 }
 
-// AnswerWebAppQueryP holds parameters for the answerWebAppQuery method.
+// AnswerWebAppQuery holds parameters for the answerWebAppQuery method.
+// Since: Bot API 8.0
 // See https://core.telegram.org/bots/api#answerwebappquery
-type AnswerWebAppQueryP struct {
+type AnswerWebAppQuery struct {
 	WebAppQueryID string            `json:"web_app_query_id"`
 	Result        InlineQueryResult `json:"result"`
 }
 
 // AnswerWebAppQuery sets the result of a Web App interaction.
+// Since: Bot API 8.0
 // See https://core.telegram.org/bots/api#answerwebappquery
-func (api *API) AnswerWebAppQuery(params AnswerWebAppQueryP) (SentWebAppMessage, error) {
+func (api *API) AnswerWebAppQuery(params AnswerWebAppQuery) (SentWebAppMessage, error) {
 	req := NewRequest[SentWebAppMessage]("answerWebAppQuery", params)
 	return req.Do(api)
 }
 
 // AnswerWebAppQueryWithContext is the context-aware variant of AnswerWebAppQuery.
+// Since: Bot API 8.0
 // It executes the same request but uses ctx for cancellation and deadlines.
 // See https://core.telegram.org/bots/api#answerwebappquery
-func (api *API) AnswerWebAppQueryWithContext(ctx context.Context, params AnswerWebAppQueryP) (SentWebAppMessage, error) {
+func (api *API) AnswerWebAppQueryWithContext(ctx context.Context, params AnswerWebAppQuery) (SentWebAppMessage, error) {
 	req := NewRequest[SentWebAppMessage]("answerWebAppQuery", params)
 	return req.DoWithContext(ctx, api)
 }
 
-// SavePreparedInlineMessageP holds parameters for the savePreparedInlineMessage method.
+// SavePreparedInlineMessage holds parameters for the savePreparedInlineMessage method.
+// Since: Bot API 8.0
 // See https://core.telegram.org/bots/api#savepreparedinlinemessage
-type SavePreparedInlineMessageP struct {
+type SavePreparedInlineMessage struct {
 	UserID            int64             `json:"user_id"`
 	Result            InlineQueryResult `json:"result"`
 	AllowUserChats    bool              `json:"allow_user_chats,omitempty"`
@@ -63,16 +70,43 @@ type SavePreparedInlineMessageP struct {
 }
 
 // SavePreparedInlineMessage stores a prepared message for Mini App users.
+// Since: Bot API 8.0
 // See https://core.telegram.org/bots/api#savepreparedinlinemessage
-func (api *API) SavePreparedInlineMessage(params SavePreparedInlineMessageP) (PreparedInlineMessage, error) {
+func (api *API) SavePreparedInlineMessage(params SavePreparedInlineMessage) (PreparedInlineMessage, error) {
 	req := NewRequest[PreparedInlineMessage]("savePreparedInlineMessage", params)
 	return req.Do(api)
 }
 
 // SavePreparedInlineMessageWithContext is the context-aware variant of SavePreparedInlineMessage.
+// Since: Bot API 8.0
 // It executes the same request but uses ctx for cancellation and deadlines.
 // See https://core.telegram.org/bots/api#savepreparedinlinemessage
-func (api *API) SavePreparedInlineMessageWithContext(ctx context.Context, params SavePreparedInlineMessageP) (PreparedInlineMessage, error) {
+func (api *API) SavePreparedInlineMessageWithContext(ctx context.Context, params SavePreparedInlineMessage) (PreparedInlineMessage, error) {
 	req := NewRequest[PreparedInlineMessage]("savePreparedInlineMessage", params)
 	return req.DoWithContext(ctx, api)
 }
+
+// SavePreparedKeyboardButton holds parameters for the savePreparedKeyboardButton method.
+// Since: Bot API 8.0
+// See https://core.telegram.org/bots/api#savepreparedkeyboardbutton
+type SavePreparedKeyboardButton struct {
+	UserID int64          `json:"user_id"`
+	Button KeyboardButton `json:"button"`
+}
+
+// SavePreparedKeyboardButton stores a prepared keyboard button for Mini App users.
+// Since: Bot API 8.0
+// See https://core.telegram.org/bots/api#savepreparedkeyboardbutton
+func (api *API) SavePreparedKeyboardButton(params SavePreparedKeyboardButton) (PreparedKeyboardButton, error) {
+	req := NewRequest[PreparedKeyboardButton]("savePreparedKeyboardButton", params)
+	return req.Do(api)
+}
+
+// SavePreparedKeyboardButtonWithContext is the context-aware variant of SavePreparedKeyboardButton.
+// Since: Bot API 8.0
+// It executes the same request but uses ctx for cancellation and deadlines.
+// See https://core.telegram.org/bots/api#savepreparedkeyboardbutton
+func (api *API) SavePreparedKeyboardButtonWithContext(ctx context.Context, params SavePreparedKeyboardButton) (PreparedKeyboardButton, error) {
+	req := NewRequest[PreparedKeyboardButton]("savePreparedKeyboardButton", params)
+	return req.DoWithContext(ctx, api)
+}

tgapi/inline_types.go

@@ -1,10 +1,12 @@
 package tgapi
 
 // InlineQueryResult is a JSON-serializable inline query result object.
+// Since: Bot API 1.7
 // See https://core.telegram.org/bots/api#inlinequeryresult
 type InlineQueryResult map[string]any
 
 // InlineQueryResultsButton represents a button shown above inline query results.
+// Since: Bot API 6.3
 // See https://core.telegram.org/bots/api#inlinequeryresultsbutton
 type InlineQueryResultsButton struct {
 	Text           string      `json:"text"`
@@ -13,14 +15,23 @@ type InlineQueryResultsButton struct {
 }
 
 // SentWebAppMessage describes an inline message sent by a Web App on behalf of a user.
+// Since: Bot API 8.0
 // See https://core.telegram.org/bots/api#sentwebappmessage
 type SentWebAppMessage struct {
 	InlineMessageID string `json:"inline_message_id,omitempty"`
 }
 
 // PreparedInlineMessage describes a prepared inline message.
+// Since: Bot API 8.0
 // See https://core.telegram.org/bots/api#preparedinlinemessage
 type PreparedInlineMessage struct {
 	ID             string `json:"id"`
 	ExpirationDate int    `json:"expiration_date"`
 }
+
+// PreparedKeyboardButton describes a prepared keyboard button.
+// Since: Bot API 8.0
+// See https://core.telegram.org/bots/api#preparedkeyboardbutton
+type PreparedKeyboardButton struct {
+	ID string `json:"id"`
+}

tgapi/messages_methods.go

@@ -2,9 +2,10 @@ package tgapi
 
 import "context"
 
-// SendMessageP holds parameters for the sendMessage method.
+// SendMessage holds parameters for the sendMessage method.
+// Since: Bot API 1.0
 // See https://core.telegram.org/bots/api#sendmessage
-type SendMessageP struct {
+type SendMessage struct {
 	BusinessConnectionID  string `json:"business_connection_id,omitempty"`
 	ChatID                int64  `json:"chat_id"`
 	MessageThreadID       int    `json:"message_thread_id,omitempty"`
@@ -25,23 +26,26 @@ type SendMessageP struct {
 }
 
 // SendMessage sends a text message.
+// Since: Bot API 1.0
 // See https://core.telegram.org/bots/api#sendmessage
-func (api *API) SendMessage(params SendMessageP) (Message, error) {
+func (api *API) SendMessage(params SendMessage) (Message, error) {
-	req := NewRequestWithChatID[Message, SendMessageP]("sendMessage", params, params.ChatID)
+	req := NewRequestWithChatID[Message, SendMessage]("sendMessage", params, params.ChatID)
 	return req.Do(api)
 }
 
 // SendMessageWithContext is the context-aware variant of SendMessage.
+// Since: Bot API 1.0
 // It executes the same request but uses ctx for cancellation and deadlines.
 // See https://core.telegram.org/bots/api#sendmessage
-func (api *API) SendMessageWithContext(ctx context.Context, params SendMessageP) (Message, error) {
+func (api *API) SendMessageWithContext(ctx context.Context, params SendMessage) (Message, error) {
-	req := NewRequestWithChatID[Message, SendMessageP]("sendMessage", params, params.ChatID)
+	req := NewRequestWithChatID[Message, SendMessage]("sendMessage", params, params.ChatID)
 	return req.DoWithContext(ctx, api)
 }
 
-// ForwardMessageP holds parameters for the forwardMessage method.
+// ForwardMessage holds parameters for the forwardMessage method.
+// Since: Bot API 1.0
 // See https://core.telegram.org/bots/api#forwardmessage
-type ForwardMessageP struct {
+type ForwardMessage struct {
 	ChatID                int64 `json:"chat_id"`
 	MessageThreadID       int   `json:"message_thread_id,omitempty"`
 	DirectMessagesTopicID int   `json:"direct_messages_topic_id,omitempty"`
@@ -57,23 +61,26 @@ type ForwardMessageP struct {
 }
 
 // ForwardMessage forwards a message.
+// Since: Bot API 1.0
 // See https://core.telegram.org/bots/api#forwardmessage
-func (api *API) ForwardMessage(params ForwardMessageP) (Message, error) {
+func (api *API) ForwardMessage(params ForwardMessage) (Message, error) {
 	req := NewRequestWithChatID[Message]("forwardMessage", params, params.ChatID)
 	return req.Do(api)
 }
 
 // ForwardMessageWithContext is the context-aware variant of ForwardMessage.
+// Since: Bot API 1.0
 // It executes the same request but uses ctx for cancellation and deadlines.
 // See https://core.telegram.org/bots/api#forwardmessage
-func (api *API) ForwardMessageWithContext(ctx context.Context, params ForwardMessageP) (Message, error) {
+func (api *API) ForwardMessageWithContext(ctx context.Context, params ForwardMessage) (Message, error) {
 	req := NewRequestWithChatID[Message]("forwardMessage", params, params.ChatID)
 	return req.DoWithContext(ctx, api)
 }
 
-// ForwardMessagesP holds parameters for the forwardMessages method.
+// ForwardMessages holds parameters for the forwardMessages method.
+// Since: Bot API 7.0
 // See https://core.telegram.org/bots/api#forwardmessages
-type ForwardMessagesP struct {
+type ForwardMessages struct {
 	ChatID                int64 `json:"chat_id"`
 	MessageThreadID       int   `json:"message_thread_id,omitempty"`
 	DirectMessagesTopicID int   `json:"direct_messages_topic_id,omitempty"`
@@ -85,24 +92,27 @@ type ForwardMessagesP struct {
 }
 
 // ForwardMessages forwards multiple messages.
+// Since: Bot API 7.0
 // Returns an array of message IDs of the sent messages.
 // See https://core.telegram.org/bots/api#forwardmessages
-func (api *API) ForwardMessages(params ForwardMessagesP) ([]MessageID, error) {
+func (api *API) ForwardMessages(params ForwardMessages) ([]MessageID, error) {
 	req := NewRequestWithChatID[[]MessageID]("forwardMessages", params, params.ChatID)
 	return req.Do(api)
 }
 
 // ForwardMessagesWithContext is the context-aware variant of ForwardMessages.
+// Since: Bot API 7.0
 // It executes the same request but uses ctx for cancellation and deadlines.
 // See https://core.telegram.org/bots/api#forwardmessages
-func (api *API) ForwardMessagesWithContext(ctx context.Context, params ForwardMessagesP) ([]MessageID, error) {
+func (api *API) ForwardMessagesWithContext(ctx context.Context, params ForwardMessages) ([]MessageID, error) {
 	req := NewRequestWithChatID[[]MessageID]("forwardMessages", params, params.ChatID)
 	return req.DoWithContext(ctx, api)
 }
 
-// CopyMessageP holds parameters for the copyMessage method.
+// CopyMessage holds parameters for the copyMessage method.
+// Since: Bot API 5.0
 // See https://core.telegram.org/bots/api#copymessage
-type CopyMessageP struct {
+type CopyMessage struct {
 	ChatID                int64 `json:"chat_id"`
 	MessageThreadID       int   `json:"message_thread_id,omitempty"`
 	DirectMessagesTopicID int   `json:"direct_messages_topic_id,omitempty"`
@@ -126,9 +136,10 @@ type CopyMessageP struct {
 }
 
 // CopyMessage copies a message.
+// Since: Bot API 5.0
 // Returns the MessageID of the sent copy.
 // See https://core.telegram.org/bots/api#copymessage
-func (api *API) CopyMessage(params CopyMessageP) (int, error) {
+func (api *API) CopyMessage(params CopyMessage) (int, error) {
 	msgID, err := NewRequestWithChatID[MessageID]("copyMessage", params, params.ChatID).Do(api)
 	if err != nil {
 		return 0, err
@@ -137,9 +148,10 @@ func (api *API) CopyMessage(params CopyMessageP) (int, error) {
 }
 
 // CopyMessageWithContext is the context-aware variant of CopyMessage.
+// Since: Bot API 5.0
 // It executes the same request but uses ctx for cancellation and deadlines.
 // See https://core.telegram.org/bots/api#copymessage
-func (api *API) CopyMessageWithContext(ctx context.Context, params CopyMessageP) (int, error) {
+func (api *API) CopyMessageWithContext(ctx context.Context, params CopyMessage) (int, error) {
 	msgID, err := NewRequestWithChatID[MessageID]("copyMessage", params, params.ChatID).DoWithContext(ctx, api)
 	if err != nil {
 		return 0, err
@@ -147,9 +159,10 @@ func (api *API) CopyMessageWithContext(ctx context.Context, params CopyMessageP)
 	return msgID.MessageID, nil
 }
 
-// CopyMessagesP holds parameters for the copyMessages method.
+// CopyMessages holds parameters for the copyMessages method.
+// Since: Bot API 7.0
 // See https://core.telegram.org/bots/api#copymessages
-type CopyMessagesP struct {
+type CopyMessages struct {
 	ChatID                int64 `json:"chat_id"`
 	MessageThreadID       int   `json:"message_thread_id,omitempty"`
 	DirectMessagesTopicID int   `json:"direct_messages_topic_id,omitempty"`
@@ -162,24 +175,27 @@ type CopyMessagesP struct {
 }
 
 // CopyMessages copies multiple messages.
+// Since: Bot API 7.0
 // Returns an array of message IDs of the sent copies.
 // See https://core.telegram.org/bots/api#copymessages
-func (api *API) CopyMessages(params CopyMessagesP) ([]MessageID, error) {
+func (api *API) CopyMessages(params CopyMessages) ([]MessageID, error) {
 	req := NewRequestWithChatID[[]MessageID]("copyMessages", params, params.ChatID)
 	return req.Do(api)
 }
 
 // CopyMessagesWithContext is the context-aware variant of CopyMessages.
+// Since: Bot API 7.0
 // It executes the same request but uses ctx for cancellation and deadlines.
 // See https://core.telegram.org/bots/api#copymessages
-func (api *API) CopyMessagesWithContext(ctx context.Context, params CopyMessagesP) ([]MessageID, error) {
+func (api *API) CopyMessagesWithContext(ctx context.Context, params CopyMessages) ([]MessageID, error) {
 	req := NewRequestWithChatID[[]MessageID]("copyMessages", params, params.ChatID)
 	return req.DoWithContext(ctx, api)
 }
 
-// SendLocationP holds parameters for the sendLocation method.
+// SendLocation holds parameters for the sendLocation method.
+// Since: Bot API 1.0
 // See https://core.telegram.org/bots/api#sendlocation
-type SendLocationP struct {
+type SendLocation struct {
 	BusinessConnectionID  string `json:"business_connection_id,omitempty"`
 	ChatID                int64  `json:"chat_id"`
 	MessageThreadID       int    `json:"message_thread_id,omitempty"`
@@ -203,23 +219,26 @@ type SendLocationP struct {
 }
 
 // SendLocation sends a point on the map.
+// Since: Bot API 1.0
 // See https://core.telegram.org/bots/api#sendlocation
-func (api *API) SendLocation(params SendLocationP) (Message, error) {
+func (api *API) SendLocation(params SendLocation) (Message, error) {
 	req := NewRequestWithChatID[Message]("sendLocation", params, params.ChatID)
 	return req.Do(api)
 }
 
 // SendLocationWithContext is the context-aware variant of SendLocation.
+// Since: Bot API 1.0
 // It executes the same request but uses ctx for cancellation and deadlines.
 // See https://core.telegram.org/bots/api#sendlocation
-func (api *API) SendLocationWithContext(ctx context.Context, params SendLocationP) (Message, error) {
+func (api *API) SendLocationWithContext(ctx context.Context, params SendLocation) (Message, error) {
 	req := NewRequestWithChatID[Message]("sendLocation", params, params.ChatID)
 	return req.DoWithContext(ctx, api)
 }
 
-// SendVenueP holds parameters for the sendVenue method.
+// SendVenue holds parameters for the sendVenue method.
+// Since: Bot API 2.0
 // See https://core.telegram.org/bots/api#sendvenue
-type SendVenueP struct {
+type SendVenue struct {
 	BusinessConnectionID  string `json:"business_connection_id,omitempty"`
 	ChatID                int64  `json:"chat_id"`
 	MessageThreadID       int    `json:"message_thread_id,omitempty"`
@@ -245,23 +264,26 @@ type SendVenueP struct {
 }
 
 // SendVenue sends information about a venue.
+// Since: Bot API 2.0
 // See https://core.telegram.org/bots/api#sendvenue
-func (api *API) SendVenue(params SendVenueP) (Message, error) {
+func (api *API) SendVenue(params SendVenue) (Message, error) {
 	req := NewRequestWithChatID[Message]("sendVenue", params, params.ChatID)
 	return req.Do(api)
 }
 
 // SendVenueWithContext is the context-aware variant of SendVenue.
+// Since: Bot API 2.0
 // It executes the same request but uses ctx for cancellation and deadlines.
 // See https://core.telegram.org/bots/api#sendvenue
-func (api *API) SendVenueWithContext(ctx context.Context, params SendVenueP) (Message, error) {
+func (api *API) SendVenueWithContext(ctx context.Context, params SendVenue) (Message, error) {
 	req := NewRequestWithChatID[Message]("sendVenue", params, params.ChatID)
 	return req.DoWithContext(ctx, api)
 }
 
-// SendContactP holds parameters for the sendContact method.
+// SendContact holds parameters for the sendContact method.
+// Since: Bot API 2.0
 // See https://core.telegram.org/bots/api#sendcontact
-type SendContactP struct {
+type SendContact struct {
 	BusinessConnectionID  string `json:"business_connection_id,omitempty"`
 	ChatID                int64  `json:"chat_id"`
 	MessageThreadID       int    `json:"message_thread_id,omitempty"`
@@ -283,41 +305,56 @@ type SendContactP struct {
 }
 
 // SendContact sends a phone contact.
+// Since: Bot API 2.0
 // See https://core.telegram.org/bots/api#sendcontact
-func (api *API) SendContact(params SendContactP) (Message, error) {
+func (api *API) SendContact(params SendContact) (Message, error) {
 	req := NewRequestWithChatID[Message]("sendContact", params, params.ChatID)
 	return req.Do(api)
 }
 
 // SendContactWithContext is the context-aware variant of SendContact.
+// Since: Bot API 2.0
 // It executes the same request but uses ctx for cancellation and deadlines.
 // See https://core.telegram.org/bots/api#sendcontact
-func (api *API) SendContactWithContext(ctx context.Context, params SendContactP) (Message, error) {
+func (api *API) SendContactWithContext(ctx context.Context, params SendContact) (Message, error) {
 	req := NewRequestWithChatID[Message]("sendContact", params, params.ChatID)
 	return req.DoWithContext(ctx, api)
 }
 
-// SendPollP holds parameters for the sendPoll method.
+// SendPoll holds parameters for the sendPoll method.
+// Since: Bot API 4.2
 // See https://core.telegram.org/bots/api#sendpoll
-type SendPollP struct {
+type SendPoll struct {
 	BusinessConnectionID string `json:"business_connection_id,omitempty"`
 	ChatID               int64  `json:"chat_id"`
 	MessageThreadID      int    `json:"message_thread_id,omitempty"`
 
-	Question              string            `json:"question"`
+	Question               string            `json:"question"`
-	QuestionParseMode     ParseMode         `json:"question_parse_mode,omitempty"`
+	QuestionParseMode      ParseMode         `json:"question_parse_mode,omitempty"`
-	QuestionEntities      []MessageEntity   `json:"question_entities,omitempty"`
+	QuestionEntities       []MessageEntity   `json:"question_entities,omitempty"`
-	Options               []InputPollOption `json:"options"`
+	Options                []InputPollOption `json:"options"`
-	IsAnonymous           bool              `json:"is_anonymous,omitempty"`
+	IsAnonymous            bool              `json:"is_anonymous,omitempty"`
-	Type                  PollType          `json:"type"`
+	Type                   PollType          `json:"type"`
-	AllowsMultipleAnswers bool              `json:"allows_multiple_answers,omitempty"`
+	AllowsMultipleAnswers  bool              `json:"allows_multiple_answers,omitempty"`
-	CorrectOptionID       int               `json:"correct_option_id,omitempty"`
+	AllowsRevoting         bool              `json:"allows_revoting,omitempty"`
-	Explanation           string            `json:"explanation,omitempty"`
+	ShuffleOptions         bool              `json:"shuffle_options,omitempty"`
-	ExplanationParseMode  ParseMode         `json:"explanation_parse_mode,omitempty"`
+	AllowAddingOptions     bool              `json:"allow_adding_options,omitempty"`
-	ExplanationEntities   []MessageEntity   `json:"explanation_entities,omitempty"`
+	HideResultsUntilCloses bool              `json:"hide_results_until_closes,omitempty"`
-	OpenPeriod            int               `json:"open_period,omitempty"`
+	MembersOnly            bool              `json:"members_only,omitempty"`  // Since: Bot API 10.0
-	CloseDate             int               `json:"close_date"`
+	CountryCodes           []string          `json:"country_codes,omitempty"` // Since: Bot API 10.0
-	IsClosed              bool              `json:"is_closed,omitempty"`
+	CorrectOptionIDs       []int             `json:"correct_option_ids,omitempty"`
+	Explanation            string            `json:"explanation,omitempty"`
+	ExplanationParseMode   ParseMode         `json:"explanation_parse_mode,omitempty"`
+	ExplanationEntities    []MessageEntity   `json:"explanation_entities,omitempty"`
+	ExplanationMedia       *InputPollMedia   `json:"explanation_media,omitempty"`
+	Media                  *InputPollMedia   `json:"media,omitempty"`
+	OpenPeriod             int               `json:"open_period,omitempty"`
+	CloseDate              int               `json:"close_date"`
+	IsClosed               bool              `json:"is_closed,omitempty"`
+
+	Description          string          `json:"description"`
+	DescriptionParseMode ParseMode       `json:"description_parse_mode,omitempty"`
+	DescriptionEntities  []MessageEntity `json:"description_entities,omitempty"`
 
 	DisableNotification bool   `json:"disable_notification,omitempty"`
 	ProtectContent      bool   `json:"protect_content,omitempty"`
@@ -329,23 +366,26 @@ type SendPollP struct {
 }
 
 // SendPoll sends a native poll.
+// Since: Bot API 4.2
 // See https://core.telegram.org/bots/api#sendpoll
-func (api *API) SendPoll(params SendPollP) (Message, error) {
+func (api *API) SendPoll(params SendPoll) (Message, error) {
 	req := NewRequestWithChatID[Message]("sendPoll", params, params.ChatID)
 	return req.Do(api)
 }
 
 // SendPollWithContext is the context-aware variant of SendPoll.
+// Since: Bot API 4.2
 // It executes the same request but uses ctx for cancellation and deadlines.
 // See https://core.telegram.org/bots/api#sendpoll
-func (api *API) SendPollWithContext(ctx context.Context, params SendPollP) (Message, error) {
+func (api *API) SendPollWithContext(ctx context.Context, params SendPoll) (Message, error) {
 	req := NewRequestWithChatID[Message]("sendPoll", params, params.ChatID)
 	return req.DoWithContext(ctx, api)
 }
 
-// SendChecklistP holds parameters for the sendChecklist method.
+// SendChecklist holds parameters for the sendChecklist method.
+// Since: Bot API 9.1
 // See https://core.telegram.org/bots/api#sendchecklist
-type SendChecklistP struct {
+type SendChecklist struct {
 	BusinessConnectionID string         `json:"business_connection_id"`
 	ChatID               int64          `json:"chat_id"`
 	Checklist            InputChecklist `json:"checklist"`
@@ -359,23 +399,26 @@ type SendChecklistP struct {
 }
 
 // SendChecklist sends a checklist.
+// Since: Bot API 9.1
 // See https://core.telegram.org/bots/api#sendchecklist
-func (api *API) SendChecklist(params SendChecklistP) (Message, error) {
+func (api *API) SendChecklist(params SendChecklist) (Message, error) {
 	req := NewRequestWithChatID[Message]("sendChecklist", params, params.ChatID)
 	return req.Do(api)
 }
 
 // SendChecklistWithContext is the context-aware variant of SendChecklist.
+// Since: Bot API 9.1
 // It executes the same request but uses ctx for cancellation and deadlines.
 // See https://core.telegram.org/bots/api#sendchecklist
-func (api *API) SendChecklistWithContext(ctx context.Context, params SendChecklistP) (Message, error) {
+func (api *API) SendChecklistWithContext(ctx context.Context, params SendChecklist) (Message, error) {
 	req := NewRequestWithChatID[Message]("sendChecklist", params, params.ChatID)
 	return req.DoWithContext(ctx, api)
 }
 
-// SendDiceP holds parameters for the sendDice method.
+// SendDice holds parameters for the sendDice method.
+// Since: Bot API 4.7
 // See https://core.telegram.org/bots/api#senddice
-type SendDiceP struct {
+type SendDice struct {
 	BusinessConnectionID  string `json:"business_connection_id,omitempty"`
 	ChatID                int64  `json:"chat_id"`
 	MessageThreadID       int    `json:"message_thread_id,omitempty"`
@@ -394,23 +437,26 @@ type SendDiceP struct {
 }
 
 // SendDice sends a dice, which will have a random value.
+// Since: Bot API 4.7
 // See https://core.telegram.org/bots/api#senddice
-func (api *API) SendDice(params SendDiceP) (Message, error) {
+func (api *API) SendDice(params SendDice) (Message, error) {
 	req := NewRequestWithChatID[Message]("sendDice", params, params.ChatID)
 	return req.Do(api)
 }
 
 // SendDiceWithContext is the context-aware variant of SendDice.
+// Since: Bot API 4.7
 // It executes the same request but uses ctx for cancellation and deadlines.
 // See https://core.telegram.org/bots/api#senddice
-func (api *API) SendDiceWithContext(ctx context.Context, params SendDiceP) (Message, error) {
+func (api *API) SendDiceWithContext(ctx context.Context, params SendDice) (Message, error) {
 	req := NewRequestWithChatID[Message]("sendDice", params, params.ChatID)
 	return req.DoWithContext(ctx, api)
 }
 
-// SendMessageDraftP holds parameters for the sendMessageDraft method.
+// SendMessageDraft holds parameters for the sendMessageDraft method.
+// Since: Bot API 9.1
 // See https://core.telegram.org/bots/api#sendmessagedraft
-type SendMessageDraftP struct {
+type SendMessageDraft struct {
 	ChatID          int64           `json:"chat_id"`
 	MessageThreadID int             `json:"message_thread_id,omitempty"`
 	DraftID         uint64          `json:"draft_id"`
@@ -420,24 +466,27 @@ type SendMessageDraftP struct {
 }
 
 // SendMessageDraft sends or updates a draft message in the target chat.
+// Since: Bot API 9.1
 // Returns True on success.
 // See https://core.telegram.org/bots/api#sendmessagedraft
-func (api *API) SendMessageDraft(params SendMessageDraftP) (bool, error) {
+func (api *API) SendMessageDraft(params SendMessageDraft) (bool, error) {
 	req := NewRequestWithChatID[bool]("sendMessageDraft", params, params.ChatID)
 	return req.Do(api)
 }
 
 // SendMessageDraftWithContext is the context-aware variant of SendMessageDraft.
+// Since: Bot API 9.1
 // It executes the same request but uses ctx for cancellation and deadlines.
 // See https://core.telegram.org/bots/api#sendmessagedraft
-func (api *API) SendMessageDraftWithContext(ctx context.Context, params SendMessageDraftP) (bool, error) {
+func (api *API) SendMessageDraftWithContext(ctx context.Context, params SendMessageDraft) (bool, error) {
 	req := NewRequestWithChatID[bool]("sendMessageDraft", params, params.ChatID)
 	return req.DoWithContext(ctx, api)
 }
 
-// SendChatActionP holds parameters for the sendChatAction method.
+// SendChatAction holds parameters for the sendChatAction method.
+// Since: Bot API 1.0
 // See https://core.telegram.org/bots/api#sendchataction
-type SendChatActionP struct {
+type SendChatAction struct {
 	BusinessConnectionID string         `json:"business_connection_id,omitempty"`
 	ChatID               int64          `json:"chat_id"`
 	MessageThreadID      int            `json:"message_thread_id,omitempty"`
@@ -445,49 +494,55 @@ type SendChatActionP struct {
 }
 
 // SendChatAction sends a chat action (typing, uploading photo, etc.).
+// Since: Bot API 1.0
 // Returns True on success.
 // See https://core.telegram.org/bots/api#sendchataction
-func (api *API) SendChatAction(params SendChatActionP) (bool, error) {
+func (api *API) SendChatAction(params SendChatAction) (bool, error) {
 	req := NewRequestWithChatID[bool]("sendChatAction", params, params.ChatID)
 	return req.Do(api)
 }
 
 // SendChatActionWithContext is the context-aware variant of SendChatAction.
+// Since: Bot API 1.0
 // It executes the same request but uses ctx for cancellation and deadlines.
 // See https://core.telegram.org/bots/api#sendchataction
-func (api *API) SendChatActionWithContext(ctx context.Context, params SendChatActionP) (bool, error) {
+func (api *API) SendChatActionWithContext(ctx context.Context, params SendChatAction) (bool, error) {
 	req := NewRequestWithChatID[bool]("sendChatAction", params, params.ChatID)
 	return req.DoWithContext(ctx, api)
 }
 
-// SetMessageReactionP holds parameters for the setMessageReaction method.
+// SetMessageReaction holds parameters for the setMessageReaction method.
+// Since: Bot API 7.0
 // See https://core.telegram.org/bots/api#setmessagereaction
-type SetMessageReactionP struct {
+type SetMessageReaction struct {
 	ChatID    int64          `json:"chat_id"`
-	MessageId int            `json:"message_id"`
+	MessageID int            `json:"message_id"`
 	Reaction  []ReactionType `json:"reaction"`
 	IsBig     bool           `json:"is_big,omitempty"`
 }
 
 // SetMessageReaction changes the chosen reaction on a message.
+// Since: Bot API 7.0
 // Returns True on success.
 // See https://core.telegram.org/bots/api#setmessagereaction
-func (api *API) SetMessageReaction(params SetMessageReactionP) (bool, error) {
+func (api *API) SetMessageReaction(params SetMessageReaction) (bool, error) {
 	req := NewRequestWithChatID[bool]("setMessageReaction", params, params.ChatID)
 	return req.Do(api)
 }
 
 // SetMessageReactionWithContext is the context-aware variant of SetMessageReaction.
+// Since: Bot API 7.0
 // It executes the same request but uses ctx for cancellation and deadlines.
 // See https://core.telegram.org/bots/api#setmessagereaction
-func (api *API) SetMessageReactionWithContext(ctx context.Context, params SetMessageReactionP) (bool, error) {
+func (api *API) SetMessageReactionWithContext(ctx context.Context, params SetMessageReaction) (bool, error) {
 	req := NewRequestWithChatID[bool]("setMessageReaction", params, params.ChatID)
 	return req.DoWithContext(ctx, api)
 }
 
-// EditMessageTextP holds parameters for the editMessageText method.
+// EditMessageText holds parameters for the editMessageText method.
+// Since: Bot API 2.0
 // See https://core.telegram.org/bots/api#editmessagetext
-type EditMessageTextP struct {
+type EditMessageText struct {
 	BusinessConnectionID string              `json:"business_connection_id,omitempty"`
 	ChatID               int64               `json:"chat_id,omitempty"`
 	MessageID            int                 `json:"message_id,omitempty"`
@@ -500,10 +555,11 @@ type EditMessageTextP struct {
 }
 
 // EditMessageText edits text messages.
+// Since: Bot API 2.0
 // If inline_message_id is provided, returns a boolean success flag;
 // otherwise returns the edited Message.
 // See https://core.telegram.org/bots/api#editmessagetext
-func (api *API) EditMessageText(params EditMessageTextP) (Message, bool, error) {
+func (api *API) EditMessageText(params EditMessageText) (Message, bool, error) {
 	var zero Message
 	if params.InlineMessageID != "" {
 		req := NewRequestWithChatID[bool]("editMessageText", params, params.ChatID)
@@ -516,9 +572,10 @@ func (api *API) EditMessageText(params EditMessageTextP) (Message, bool, error)
 }
 
 // EditMessageTextWithContext is the context-aware variant of EditMessageText.
+// Since: Bot API 2.0
 // It executes the same request but uses ctx for cancellation and deadlines.
 // See https://core.telegram.org/bots/api#editmessagetext
-func (api *API) EditMessageTextWithContext(ctx context.Context, params EditMessageTextP) (Message, bool, error) {
+func (api *API) EditMessageTextWithContext(ctx context.Context, params EditMessageText) (Message, bool, error) {
 	var zero Message
 	if params.InlineMessageID != "" {
 		req := NewRequestWithChatID[bool]("editMessageText", params, params.ChatID)
@@ -530,9 +587,10 @@ func (api *API) EditMessageTextWithContext(ctx context.Context, params EditMessa
 	return res, false, err
 }
 
-// EditMessageCaptionP holds parameters for the editMessageCaption method.
+// EditMessageCaption holds parameters for the editMessageCaption method.
+// Since: Bot API 2.0
 // See https://core.telegram.org/bots/api#editmessagecaption
-type EditMessageCaptionP struct {
+type EditMessageCaption struct {
 	BusinessConnectionID  string          `json:"business_connection_id,omitempty"`
 	ChatID                int64           `json:"chat_id,omitempty"`
 	MessageID             int             `json:"message_id,omitempty"`
@@ -545,10 +603,11 @@ type EditMessageCaptionP struct {
 }
 
 // EditMessageCaption edits captions of messages.
+// Since: Bot API 2.0
 // If inline_message_id is provided, returns a boolean success flag;
 // otherwise returns the edited Message.
 // See https://core.telegram.org/bots/api#editmessagecaption
-func (api *API) EditMessageCaption(params EditMessageCaptionP) (Message, bool, error) {
+func (api *API) EditMessageCaption(params EditMessageCaption) (Message, bool, error) {
 	var zero Message
 	if params.InlineMessageID != "" {
 		req := NewRequestWithChatID[bool]("editMessageCaption", params, params.ChatID)
@@ -561,9 +620,10 @@ func (api *API) EditMessageCaption(params EditMessageCaptionP) (Message, bool, e
 }
 
 // EditMessageCaptionWithContext is the context-aware variant of EditMessageCaption.
+// Since: Bot API 2.0
 // It executes the same request but uses ctx for cancellation and deadlines.
 // See https://core.telegram.org/bots/api#editmessagecaption
-func (api *API) EditMessageCaptionWithContext(ctx context.Context, params EditMessageCaptionP) (Message, bool, error) {
+func (api *API) EditMessageCaptionWithContext(ctx context.Context, params EditMessageCaption) (Message, bool, error) {
 	var zero Message
 	if params.InlineMessageID != "" {
 		req := NewRequestWithChatID[bool]("editMessageCaption", params, params.ChatID)
@@ -575,9 +635,10 @@ func (api *API) EditMessageCaptionWithContext(ctx context.Context, params EditMe
 	return res, false, err
 }
 
-// EditMessageMediaP holds parameters for the editMessageMedia method.
+// EditMessageMedia holds parameters for the editMessageMedia method.
+// Since: Bot API 4.0
 // See https://core.telegram.org/bots/api#editmessagemedia
-type EditMessageMediaP struct {
+type EditMessageMedia struct {
 	BusinessConnectionID string                `json:"business_connection_id,omitempty"`
 	ChatID               int64                 `json:"chat_id,omitempty"`
 	MessageID            int                   `json:"message_id,omitempty"`
@@ -587,10 +648,11 @@ type EditMessageMediaP struct {
 }
 
 // EditMessageMedia edits media messages.
+// Since: Bot API 4.0
 // If inline_message_id is provided, returns a boolean success flag;
 // otherwise returns the edited Message.
 // See https://core.telegram.org/bots/api#editmessagemedia
-func (api *API) EditMessageMedia(params EditMessageMediaP) (Message, bool, error) {
+func (api *API) EditMessageMedia(params EditMessageMedia) (Message, bool, error) {
 	var zero Message
 	if params.InlineMessageID != "" {
 		req := NewRequestWithChatID[bool]("editMessageMedia", params, params.ChatID)
@@ -603,9 +665,10 @@ func (api *API) EditMessageMedia(params EditMessageMediaP) (Message, bool, error
 }
 
 // EditMessageMediaWithContext is the context-aware variant of EditMessageMedia.
+// Since: Bot API 4.0
 // It executes the same request but uses ctx for cancellation and deadlines.
 // See https://core.telegram.org/bots/api#editmessagemedia
-func (api *API) EditMessageMediaWithContext(ctx context.Context, params EditMessageMediaP) (Message, bool, error) {
+func (api *API) EditMessageMediaWithContext(ctx context.Context, params EditMessageMedia) (Message, bool, error) {
 	var zero Message
 	if params.InlineMessageID != "" {
 		req := NewRequestWithChatID[bool]("editMessageMedia", params, params.ChatID)
@@ -617,9 +680,10 @@ func (api *API) EditMessageMediaWithContext(ctx context.Context, params EditMess
 	return res, false, err
 }
 
-// EditMessageLiveLocationP holds parameters for the editMessageLiveLocation method.
+// EditMessageLiveLocation holds parameters for the editMessageLiveLocation method.
+// Since: Bot API 3.4
 // See https://core.telegram.org/bots/api#editmessagelivelocation
-type EditMessageLiveLocationP struct {
+type EditMessageLiveLocation struct {
 	BusinessConnectionID string `json:"business_connection_id,omitempty"`
 	ChatID               int64  `json:"chat_id,omitempty"`
 	MessageID            int    `json:"message_id,omitempty"`
@@ -635,10 +699,11 @@ type EditMessageLiveLocationP struct {
 }
 
 // EditMessageLiveLocation edits live location messages.
+// Since: Bot API 3.4
 // If inline_message_id is provided, returns a boolean success flag;
 // otherwise returns the edited Message.
 // See https://core.telegram.org/bots/api#editmessagelivelocation
-func (api *API) EditMessageLiveLocation(params EditMessageLiveLocationP) (Message, bool, error) {
+func (api *API) EditMessageLiveLocation(params EditMessageLiveLocation) (Message, bool, error) {
 	var zero Message
 	if params.InlineMessageID != "" {
 		req := NewRequestWithChatID[bool]("editMessageLiveLocation", params, params.ChatID)
@@ -651,9 +716,10 @@ func (api *API) EditMessageLiveLocation(params EditMessageLiveLocationP) (Messag
 }
 
 // EditMessageLiveLocationWithContext is the context-aware variant of EditMessageLiveLocation.
+// Since: Bot API 3.4
 // It executes the same request but uses ctx for cancellation and deadlines.
 // See https://core.telegram.org/bots/api#editmessagelivelocation
-func (api *API) EditMessageLiveLocationWithContext(ctx context.Context, params EditMessageLiveLocationP) (Message, bool, error) {
+func (api *API) EditMessageLiveLocationWithContext(ctx context.Context, params EditMessageLiveLocation) (Message, bool, error) {
 	var zero Message
 	if params.InlineMessageID != "" {
 		req := NewRequestWithChatID[bool]("editMessageLiveLocation", params, params.ChatID)
@@ -665,9 +731,10 @@ func (api *API) EditMessageLiveLocationWithContext(ctx context.Context, params E
 	return res, false, err
 }
 
-// StopMessageLiveLocationP holds parameters for the stopMessageLiveLocation method.
+// StopMessageLiveLocation holds parameters for the stopMessageLiveLocation method.
+// Since: Bot API 3.4
 // See https://core.telegram.org/bots/api#stopmessagelivelocation
-type StopMessageLiveLocationP struct {
+type StopMessageLiveLocation struct {
 	BusinessConnectionID string                `json:"business_connection_id,omitempty"`
 	ChatID               int64                 `json:"chat_id,omitempty"`
 	MessageID            int                   `json:"message_id,omitempty"`
@@ -676,10 +743,11 @@ type StopMessageLiveLocationP struct {
 }
 
 // StopMessageLiveLocation stops a live location message.
+// Since: Bot API 3.4
 // If inline_message_id is provided, returns a boolean success flag;
 // otherwise returns the edited Message.
 // See https://core.telegram.org/bots/api#stopmessagelivelocation
-func (api *API) StopMessageLiveLocation(params StopMessageLiveLocationP) (Message, bool, error) {
+func (api *API) StopMessageLiveLocation(params StopMessageLiveLocation) (Message, bool, error) {
 	var zero Message
 	if params.InlineMessageID != "" {
 		req := NewRequestWithChatID[bool]("stopMessageLiveLocation", params, params.ChatID)
@@ -692,9 +760,10 @@ func (api *API) StopMessageLiveLocation(params StopMessageLiveLocationP) (Messag
 }
 
 // StopMessageLiveLocationWithContext is the context-aware variant of StopMessageLiveLocation.
+// Since: Bot API 3.4
 // It executes the same request but uses ctx for cancellation and deadlines.
 // See https://core.telegram.org/bots/api#stopmessagelivelocation
-func (api *API) StopMessageLiveLocationWithContext(ctx context.Context, params StopMessageLiveLocationP) (Message, bool, error) {
+func (api *API) StopMessageLiveLocationWithContext(ctx context.Context, params StopMessageLiveLocation) (Message, bool, error) {
 	var zero Message
 	if params.InlineMessageID != "" {
 		req := NewRequestWithChatID[bool]("stopMessageLiveLocation", params, params.ChatID)
@@ -706,8 +775,10 @@ func (api *API) StopMessageLiveLocationWithContext(ctx context.Context, params S
 	return res, false, err
 }
 
-// EditMessageChecklistP holds parameters for the editMessageChecklist method.
+// EditMessageChecklist holds parameters for the editMessageChecklist method.
-type EditMessageChecklistP struct {
+// Since: Bot API 9.1
+// See https://core.telegram.org/bots/api#editmessagechecklist
+type EditMessageChecklist struct {
 	BusinessConnectionID string                `json:"business_connection_id"`
 	ChatID               int64                 `json:"chat_id"`
 	MessageID            int                   `json:"message_id"`
@@ -716,23 +787,26 @@ type EditMessageChecklistP struct {
 }
 
 // EditMessageChecklist edits a checklist message.
+// Since: Bot API 9.1
 // See https://core.telegram.org/bots/api#editmessagechecklist
-func (api *API) EditMessageChecklist(params EditMessageChecklistP) (Message, error) {
+func (api *API) EditMessageChecklist(params EditMessageChecklist) (Message, error) {
 	req := NewRequestWithChatID[Message]("editMessageChecklist", params, params.ChatID)
 	return req.Do(api)
 }
 
 // EditMessageChecklistWithContext is the context-aware variant of EditMessageChecklist.
+// Since: Bot API 9.1
 // It executes the same request but uses ctx for cancellation and deadlines.
 // See https://core.telegram.org/bots/api#editmessagechecklist
-func (api *API) EditMessageChecklistWithContext(ctx context.Context, params EditMessageChecklistP) (Message, error) {
+func (api *API) EditMessageChecklistWithContext(ctx context.Context, params EditMessageChecklist) (Message, error) {
 	req := NewRequestWithChatID[Message]("editMessageChecklist", params, params.ChatID)
 	return req.DoWithContext(ctx, api)
 }
 
-// EditMessageReplyMarkupP holds parameters for the editMessageReplyMarkup method.
+// EditMessageReplyMarkup holds parameters for the editMessageReplyMarkup method.
+// Since: Bot API 2.0
 // See https://core.telegram.org/bots/api#editmessagereplymarkup
-type EditMessageReplyMarkupP struct {
+type EditMessageReplyMarkup struct {
 	BusinessConnectionID string                `json:"business_connection_id,omitempty"`
 	ChatID               int64                 `json:"chat_id,omitempty"`
 	MessageID            int                   `json:"message_id,omitempty"`
@@ -741,10 +815,11 @@ type EditMessageReplyMarkupP struct {
 }
 
 // EditMessageReplyMarkup edits only the reply markup of messages.
+// Since: Bot API 2.0
 // If inline_message_id is provided, returns a boolean success flag;
 // otherwise returns the edited Message.
 // See https://core.telegram.org/bots/api#editmessagereplymarkup
-func (api *API) EditMessageReplyMarkup(params EditMessageReplyMarkupP) (Message, bool, error) {
+func (api *API) EditMessageReplyMarkup(params EditMessageReplyMarkup) (Message, bool, error) {
 	var zero Message
 	if params.InlineMessageID != "" {
 		req := NewRequestWithChatID[bool]("editMessageReplyMarkup", params, params.ChatID)
@@ -757,9 +832,10 @@ func (api *API) EditMessageReplyMarkup(params EditMessageReplyMarkupP) (Message,
 }
 
 // EditMessageReplyMarkupWithContext is the context-aware variant of EditMessageReplyMarkup.
+// Since: Bot API 2.0
 // It executes the same request but uses ctx for cancellation and deadlines.
 // See https://core.telegram.org/bots/api#editmessagereplymarkup
-func (api *API) EditMessageReplyMarkupWithContext(ctx context.Context, params EditMessageReplyMarkupP) (Message, bool, error) {
+func (api *API) EditMessageReplyMarkupWithContext(ctx context.Context, params EditMessageReplyMarkup) (Message, bool, error) {
 	var zero Message
 	if params.InlineMessageID != "" {
 		req := NewRequestWithChatID[bool]("editMessageReplyMarkup", params, params.ChatID)
@@ -771,9 +847,10 @@ func (api *API) EditMessageReplyMarkupWithContext(ctx context.Context, params Ed
 	return res, false, err
 }
 
-// StopPollP holds parameters for the stopPoll method.
+// StopPoll holds parameters for the stopPoll method.
+// Since: Bot API 4.2
 // See https://core.telegram.org/bots/api#stoppoll
-type StopPollP struct {
+type StopPoll struct {
 	BusinessConnectionID string                `json:"business_connection_id,omitempty"`
 	ChatID               int64                 `json:"chat_id"`
 	MessageID            int                   `json:"message_id"`
@@ -781,118 +858,133 @@ type StopPollP struct {
 }
 
 // StopPoll stops a poll that was sent by the bot.
+// Since: Bot API 4.2
 // Returns the stopped Poll.
 // See https://core.telegram.org/bots/api#stoppoll
-func (api *API) StopPoll(params StopPollP) (Poll, error) {
+func (api *API) StopPoll(params StopPoll) (Poll, error) {
 	req := NewRequestWithChatID[Poll]("stopPoll", params, params.ChatID)
 	return req.Do(api)
 }
 
 // StopPollWithContext is the context-aware variant of StopPoll.
+// Since: Bot API 4.2
 // It executes the same request but uses ctx for cancellation and deadlines.
 // See https://core.telegram.org/bots/api#stoppoll
-func (api *API) StopPollWithContext(ctx context.Context, params StopPollP) (Poll, error) {
+func (api *API) StopPollWithContext(ctx context.Context, params StopPoll) (Poll, error) {
 	req := NewRequestWithChatID[Poll]("stopPoll", params, params.ChatID)
 	return req.DoWithContext(ctx, api)
 }
 
-// ApproveSuggestedPostP holds parameters for the approveSuggestedPost method.
+// ApproveSuggestedPost holds parameters for the approveSuggestedPost method.
+// Since: Bot API 9.2
 // See https://core.telegram.org/bots/api#approvesuggestedpost
-type ApproveSuggestedPostP struct {
+type ApproveSuggestedPost struct {
 	ChatID    int64 `json:"chat_id"`
 	MessageID int   `json:"message_id"`
 	SendDate  int   `json:"send_date,omitempty"`
 }
 
 // ApproveSuggestedPost approves a suggested channel post.
+// Since: Bot API 9.2
 // Returns True on success.
 // See https://core.telegram.org/bots/api#approvesuggestedpost
-func (api *API) ApproveSuggestedPost(params ApproveSuggestedPostP) (bool, error) {
+func (api *API) ApproveSuggestedPost(params ApproveSuggestedPost) (bool, error) {
 	req := NewRequestWithChatID[bool]("approveSuggestedPost", params, params.ChatID)
 	return req.Do(api)
 }
 
 // ApproveSuggestedPostWithContext is the context-aware variant of ApproveSuggestedPost.
+// Since: Bot API 9.2
 // It executes the same request but uses ctx for cancellation and deadlines.
 // See https://core.telegram.org/bots/api#approvesuggestedpost
-func (api *API) ApproveSuggestedPostWithContext(ctx context.Context, params ApproveSuggestedPostP) (bool, error) {
+func (api *API) ApproveSuggestedPostWithContext(ctx context.Context, params ApproveSuggestedPost) (bool, error) {
 	req := NewRequestWithChatID[bool]("approveSuggestedPost", params, params.ChatID)
 	return req.DoWithContext(ctx, api)
 }
 
-// DeclineSuggestedPostP holds parameters for the declineSuggestedPost method.
+// DeclineSuggestedPost holds parameters for the declineSuggestedPost method.
+// Since: Bot API 9.2
 // See https://core.telegram.org/bots/api#declinesuggestedpost
-type DeclineSuggestedPostP struct {
+type DeclineSuggestedPost struct {
 	ChatID    int64  `json:"chat_id"`
 	MessageID int    `json:"message_id"`
 	Comment   string `json:"comment,omitempty"`
 }
 
 // DeclineSuggestedPost declines a suggested channel post.
+// Since: Bot API 9.2
 // Returns True on success.
 // See https://core.telegram.org/bots/api#declinesuggestedpost
-func (api *API) DeclineSuggestedPost(params DeclineSuggestedPostP) (bool, error) {
+func (api *API) DeclineSuggestedPost(params DeclineSuggestedPost) (bool, error) {
 	req := NewRequestWithChatID[bool]("declineSuggestedPost", params, params.ChatID)
 	return req.Do(api)
 }
 
 // DeclineSuggestedPostWithContext is the context-aware variant of DeclineSuggestedPost.
+// Since: Bot API 9.2
 // It executes the same request but uses ctx for cancellation and deadlines.
 // See https://core.telegram.org/bots/api#declinesuggestedpost
-func (api *API) DeclineSuggestedPostWithContext(ctx context.Context, params DeclineSuggestedPostP) (bool, error) {
+func (api *API) DeclineSuggestedPostWithContext(ctx context.Context, params DeclineSuggestedPost) (bool, error) {
 	req := NewRequestWithChatID[bool]("declineSuggestedPost", params, params.ChatID)
 	return req.DoWithContext(ctx, api)
 }
 
-// DeleteMessageP holds parameters for the deleteMessage method.
+// DeleteMessage holds parameters for the deleteMessage method.
+// Since: Bot API 3.0
 // See https://core.telegram.org/bots/api#deletemessage
-type DeleteMessageP struct {
+type DeleteMessage struct {
 	ChatID    int64 `json:"chat_id"`
 	MessageID int   `json:"message_id"`
 }
 
 // DeleteMessage deletes a message.
+// Since: Bot API 3.0
 // Returns True on success.
 // See https://core.telegram.org/bots/api#deletemessage
-func (api *API) DeleteMessage(params DeleteMessageP) (bool, error) {
+func (api *API) DeleteMessage(params DeleteMessage) (bool, error) {
 	req := NewRequestWithChatID[bool]("deleteMessage", params, params.ChatID)
 	return req.Do(api)
 }
 
 // DeleteMessageWithContext is the context-aware variant of DeleteMessage.
+// Since: Bot API 3.0
 // It executes the same request but uses ctx for cancellation and deadlines.
 // See https://core.telegram.org/bots/api#deletemessage
-func (api *API) DeleteMessageWithContext(ctx context.Context, params DeleteMessageP) (bool, error) {
+func (api *API) DeleteMessageWithContext(ctx context.Context, params DeleteMessage) (bool, error) {
 	req := NewRequestWithChatID[bool]("deleteMessage", params, params.ChatID)
 	return req.DoWithContext(ctx, api)
 }
 
-// DeleteMessagesP holds parameters for the deleteMessages method.
+// DeleteMessages holds parameters for the deleteMessages method.
+// Since: Bot API 7.0
 // See https://core.telegram.org/bots/api#deletemessages
-type DeleteMessagesP struct {
+type DeleteMessages struct {
 	ChatID     int64 `json:"chat_id"`
 	MessageIDs []int `json:"message_ids"`
 }
 
 // DeleteMessages deletes multiple messages at once.
+// Since: Bot API 7.0
 // Returns True on success.
 // See https://core.telegram.org/bots/api#deletemessages
-func (api *API) DeleteMessages(params DeleteMessagesP) (bool, error) {
+func (api *API) DeleteMessages(params DeleteMessages) (bool, error) {
 	req := NewRequestWithChatID[bool]("deleteMessages", params, params.ChatID)
 	return req.Do(api)
 }
 
 // DeleteMessagesWithContext is the context-aware variant of DeleteMessages.
+// Since: Bot API 7.0
 // It executes the same request but uses ctx for cancellation and deadlines.
 // See https://core.telegram.org/bots/api#deletemessages
-func (api *API) DeleteMessagesWithContext(ctx context.Context, params DeleteMessagesP) (bool, error) {
+func (api *API) DeleteMessagesWithContext(ctx context.Context, params DeleteMessages) (bool, error) {
 	req := NewRequestWithChatID[bool]("deleteMessages", params, params.ChatID)
 	return req.DoWithContext(ctx, api)
 }
 
-// AnswerCallbackQueryP holds parameters for the answerCallbackQuery method.
+// AnswerCallbackQuery holds parameters for the answerCallbackQuery method.
+// Since: Bot API 2.0
 // See https://core.telegram.org/bots/api#answercallbackquery
-type AnswerCallbackQueryP struct {
+type AnswerCallbackQuery struct {
 	CallbackQueryID string `json:"callback_query_id"`
 	Text            string `json:"text,omitempty"`
 	ShowAlert       bool   `json:"show_alert,omitempty"`
@@ -901,17 +993,99 @@ type AnswerCallbackQueryP struct {
 }
 
 // AnswerCallbackQuery sends answers to callback queries sent from inline keyboards.
+// Since: Bot API 2.0
 // Returns True on success.
 // See https://core.telegram.org/bots/api#answercallbackquery
-func (api *API) AnswerCallbackQuery(params AnswerCallbackQueryP) (bool, error) {
+func (api *API) AnswerCallbackQuery(params AnswerCallbackQuery) (bool, error) {
 	req := NewRequest[bool]("answerCallbackQuery", params)
 	return req.Do(api)
 }
 
 // AnswerCallbackQueryWithContext is the context-aware variant of AnswerCallbackQuery.
+// Since: Bot API 2.0
 // It executes the same request but uses ctx for cancellation and deadlines.
 // See https://core.telegram.org/bots/api#answercallbackquery
-func (api *API) AnswerCallbackQueryWithContext(ctx context.Context, params AnswerCallbackQueryP) (bool, error) {
+func (api *API) AnswerCallbackQueryWithContext(ctx context.Context, params AnswerCallbackQuery) (bool, error) {
 	req := NewRequest[bool]("answerCallbackQuery", params)
 	return req.DoWithContext(ctx, api)
 }
+
+// AnswerGuestQuery holds parameters for the answerGuestQuery method.
+// Since: Bot API 10.0
+// See https://core.telegram.org/bots/api#answerguestquery
+type AnswerGuestQuery struct {
+	GuestQueryID string            `json:"guest_query_id"`
+	Result       InlineQueryResult `json:"result"`
+}
+
+// AnswerGuestQuery answers a guest query.
+// Since: Bot API 10.0
+// See https://core.telegram.org/bots/api#answerguestquery
+func (api *API) AnswerGuestQuery(params AnswerGuestQuery) (SentGuestMessage, error) {
+	req := NewRequest[SentGuestMessage]("answerGuestQuery", params)
+	return req.Do(api)
+}
+
+// AnswerGuestQueryWithContext is the context-aware variant of AnswerGuestQuery.
+// Since: Bot API 10.0
+// It executes the same request but uses ctx for cancellation and deadlines.
+// See https://core.telegram.org/bots/api#answerguestquery
+func (api *API) AnswerGuestQueryWithContext(ctx context.Context, params AnswerGuestQuery) (SentGuestMessage, error) {
+	req := NewRequest[SentGuestMessage]("answerGuestQuery", params)
+	return req.DoWithContext(ctx, api)
+}
+
+// DeleteAllMessageReactions holds parameters for the deleteAllMessageReactions method.
+// Since: Bot API 10.0
+// See https://core.telegram.org/bots/api#deleteallmessagereactions
+type DeleteAllMessageReactions struct {
+	ChatID      int64 `json:"chat_id"`
+	UserID      int64 `json:"user_id,omitempty"`
+	ActorChatID int64 `json:"actor_chat_id,omitempty"`
+}
+
+// DeleteAllMessageReactions deletes all reactions on a message.
+// Since: Bot API 10.0
+// Returns True on success.
+// See https://core.telegram.org/bots/api#deleteallmessagereactions
+func (api *API) DeleteAllMessageReactions(params DeleteAllMessageReactions) (bool, error) {
+	req := NewRequest[bool]("deleteAllMessageReactions", params)
+	return req.Do(api)
+}
+
+// DeleteAllMessageReactionWithContext is the context-aware variant of DeleteAllMessageReactions.
+// Since: Bot API 10.0
+// It executes the same request but uses ctx for cancellation and deadlines.
+// See https://core.telegram.org/bots/api#deleteallmessagereactions
+func (api *API) DeleteAllMessageReactionWithContext(ctx context.Context, params DeleteAllMessageReactions) (bool, error) {
+	req := NewRequest[bool]("deleteAllMessageReactions", params)
+	return req.DoWithContext(ctx, api)
+}
+
+// DeleteMessageReaction holds parameters for the deleteMessageReaction method.
+// Since: Bot API 10.0
+// See https://core.telegram.org/bots/api#deletemessagereaction
+type DeleteMessageReaction struct {
+	ChatID      int64 `json:"chat_id"`
+	MessageID   int   `json:"message_id"`
+	UserID      int64 `json:"user_id,omitempty"`
+	ActorChatID int64 `json:"actor_chat_id,omitempty"`
+}
+
+// DeleteMessageReaction deletes a reaction on a message.
+// Since: Bot API 10.0
+// Returns True on success.
+// See https://core.telegram.org/bots/api#deletemessagereaction
+func (api *API) DeleteMessageReaction(params DeleteMessageReaction) (bool, error) {
+	req := NewRequest[bool]("deleteMessageReaction", params)
+	return req.Do(api)
+}
+
+// DeleteMessageReactionWithContext is the context-aware variant of DeleteMessageReaction.
+// Since: Bot API 10.0
+// It executes the same request but uses ctx for cancellation and deadlines.
+// See https://core.telegram.org/bots/api#deletemessagereaction
+func (api *API) DeleteMessageReactionWithContext(ctx context.Context, params DeleteMessageReaction) (bool, error) {
+	req := NewRequest[bool]("deleteMessageReaction", params)
+	return req.DoWithContext(ctx, api)
+}

tgapi/messages_types.go

@@ -1,67 +1,247 @@
 package tgapi
 
-import "git.nix13.pw/scuroneko/extypes"
+import (
+	"encoding/json"
+
+	"git.scuroneko.dev/scuroneko/extypes"
+)
 
 // MessageID represents a message identifier wrapper returned by some API methods.
+// Since: Bot API 7.0
 type MessageID struct {
 	MessageID int `json:"message_id"`
 }
 
-// MessageReplyMarkup represents an inline keyboard markup for a message.
-// It is used in the Message type.
-type MessageReplyMarkup struct {
-	InlineKeyboard [][]InlineKeyboardButton `json:"inline_keyboard"`
-}
-
 // DirectMessageTopic represents a forum topic in a direct message.
+// Since: Bot API 9.2
 type DirectMessageTopic struct {
 	TopicID int64 `json:"topic_id"`
 	User    *User `json:"user,omitempty"`
 }
 
+// MessageOriginType represents the type of a message origin.
+type MessageOriginType string
+
+const (
+	MessageOriginUserType       = "user"
+	MessageOriginHiddenUserType = "hidden_user"
+	MessageOriginChatType       = "chat"
+	MessageOriginChannel        = "channel"
+)
+
+// MessageOrigin describes the origin of a message.
+// Since: Bot API 7.0
+type MessageOrigin struct {
+	Type MessageOriginType `json:"type"`
+	Date int64             `json:"date"`
+
+	SenderUser *User `json:"sender_user,omitempty"`
+
+	SenderUserName string `json:"sender_user_name,omitempty"`
+
+	SenderChat *Chat `json:"sender_chat,omitempty"`
+
+	Chat      *Chat `json:"chat,omitempty"`
+	MessageID int   `json:"message_id"`
+
+	AuthorSignature string `json:"author_signature,omitempty"`
+}
+
+// ExternalReplyInfo contains information about a message that is being replied to.
+// Since: Bot API 7.0
+type ExternalReplyInfo struct {
+	Origin             MessageOrigin       `json:"origin"`
+	Chat               *Chat               `json:"chat,omitempty"`
+	MessageID          int                 `json:"message_id,omitempty"`
+	LinkPreviewOptions *LinkPreviewOptions `json:"link_preview_options,omitempty"`
+	Animation          *Animation          `json:"animation,omitempty"`
+	Audio              *Audio              `json:"audio,omitempty"`
+	Document           *Document           `json:"document,omitempty"`
+	PaidMedia          *PaidMediaInfo      `json:"paid_media,omitempty"` // Since: Bot API 7.6
+	Photo              []PhotoSize         `json:"photo,omitempty"`
+	LivePhoto          *LivePhoto          `json:"live_photo,omitempty"` // Since: Bot API 10.0
+	Sticker            *Sticker            `json:"sticker,omitempty"`
+	Story              *Story              `json:"story,omitempty"`
+	Video              *Video              `json:"video,omitempty"`
+	VideoNote          *VideoNote          `json:"video_note,omitempty"`
+	Voice              *Voice              `json:"voice,omitempty"`
+	HasMediaSpoiler    bool                `json:"has_media_spoiler,omitempty"`
+	Checklist          *Checklist          `json:"checklist,omitempty"` // Since: Bot API 9.1
+	Contact            *Contact            `json:"contact,omitempty"`
+	Dice               *Dice               `json:"dice,omitempty"`
+	Game               *Game               `json:"game,omitempty"`
+	Giveaway           *Giveaway           `json:"giveaway,omitempty"`
+	GiveawayWinners    *GiveawayWinners    `json:"giveaway_winners,omitempty"`
+	Invoice            *Invoice            `json:"invoice,omitempty"`
+	Location           *Location           `json:"location,omitempty"`
+	Poll               *Poll               `json:"poll,omitempty"`
+	Venue              *Venue              `json:"venue,omitempty"`
+}
+
+// TextQuote contains information about the quoted part of a message.
+// Since: Bot API 7.0
+type TextQuote struct {
+	Text     string          `json:"text"`
+	Entities []MessageEntity `json:"entities"`
+	Position int             `json:"position"`
+	IsManual bool            `json:"is_manual,omitempty"`
+}
+
+// MessageAutoDeleteTimerChanged represents a service message about a change in auto-delete timer settings.
+// Since: Bot API 5.1
+type MessageAutoDeleteTimerChanged struct {
+	MessageAutoDeleteTime int `json:"message_auto_delete_time"`
+}
+
+// DirectMessagePriceChanged represents a service message about a change in the price of direct messages.
+// Since: Bot API 9.1
+type DirectMessagePriceChanged struct {
+	AreDirectMessagesEnabled bool `json:"are_direct_messages_enabled"`
+	DirectMessageStarCount   int  `json:"direct_message_star_count,omitempty"`
+}
+
+// PaidMessagePriceChanged represents a service message about a change in the price of paid messages.
+// Since: Bot API 9.x
+type PaidMessagePriceChanged struct {
+	PaidMessageStarCount int `json:"paid_message_star_count"`
+}
+
 // Message represents a Telegram message.
+// Since: Bot API 1.0
 // See https://core.telegram.org/bots/api#message
 type Message struct {
-	MessageID            int                 `json:"message_id"`
+	MessageID          int                 `json:"message_id"`
-	MessageThreadID      int                 `json:"message_thread_id,omitempty"`
+	MessageThreadID    int                 `json:"message_thread_id,omitempty"`    // Since: Bot API 6.3
-	DirectMessageTopic   *DirectMessageTopic `json:"direct_message_topic,omitempty"`
+	DirectMessageTopic *DirectMessageTopic `json:"direct_message_topic,omitempty"` // Since: Bot API 9.2
-	BusinessConnectionId string              `json:"business_connection_id,omitempty"`
+	From               *User               `json:"from,omitempty"`
-	From                 *User               `json:"from,omitempty"`
 
-	SenderChat        *Chat  `json:"sender_chat,omitempty"`
+	SenderChat           *Chat          `json:"sender_chat,omitempty"`         // Since: Bot API 5.0
-	SenderBoostCount  int    `json:"sender_boost_count,omitempty"`
+	SenderBoostCount     int            `json:"sender_boost_count,omitempty"`  // Since: Bot API 7.1
-	SenderBusinessBot *User  `json:"sender_business_bot,omitempty"`
+	SenderBusinessBot    *User          `json:"sender_business_bot,omitempty"` // Since: Bot API 7.2
-	SenderTag         string `json:"sender_tag,omitempty"`
+	SenderTag            string         `json:"sender_tag,omitempty"`          // Since: Bot API 9.5
-	Chat              *Chat  `json:"chat,omitempty"`
+	Date                 int            `json:"date"`
+	GuestQueryID         string         `json:"guest_query_id,omitempty"`         // Since: Bot API 10.0
+	BusinessConnectionID string         `json:"business_connection_id,omitempty"` // Since: Bot API 7.2
+	Chat                 *Chat          `json:"chat,omitempty"`
+	ForwardOrigin        *MessageOrigin `json:"forward_origin,omitempty"` // Since: Bot API 7.0
 
-	IsTopicMessage     bool     `json:"is_topic_message,omitempty"`
+	IsTopicMessage     bool               `json:"is_topic_message,omitempty"`     // Since: Bot API 6.3
-	IsAutomaticForward bool     `json:"is_automatic_forward,omitempty"`
+	IsAutomaticForward bool               `json:"is_automatic_forward,omitempty"` // Since: Bot API 5.5
-	IsFromOffline      bool     `json:"is_from_offline,omitempty"`
+	ReplyToMessage     *Message           `json:"reply_to_message,omitempty"`
-	IsPaidPost         bool     `json:"is_paid_post,omitempty"`
+	ExternalReply      *ExternalReplyInfo `json:"external_reply,omitempty"` // Since: Bot API 7.0
-	MediaGroupId       string   `json:"media_group_id,omitempty"`
+	Quote              *TextQuote         `json:"quote,omitempty"`          // Since: Bot API 7.0
-	AuthorSignature    string   `json:"author_signature,omitempty"`
-	PaidStarCount      int      `json:"paid_star_count,omitempty"`
-	ReplyToMessage     *Message `json:"reply_to_message,omitempty"`
 
-	Text string `json:"text"`
+	ReplyToStory           *Story `json:"reply_to_story,omitempty"`             // Since: Bot API 7.1
-
+	ReplyToChecklistTaskID int    `json:"reply_to_checklist_task_id,omitempty"` // Since: Bot API 9.1
-	Photo           extypes.Slice[PhotoSize] `json:"photo,omitempty"`
+	ReplyToPollOptionID    string `json:"reply_to_poll_option_id,omitempty"`    // Since: Bot API 9.6
-	Caption         string                   `json:"caption,omitempty"`
+	ViaBot                 *User  `json:"via_bot,omitempty"`
-	CaptionEntities []MessageEntity          `json:"caption_entities,omitempty"`
+	GuestBotCallerUser     *User  `json:"guest_bot_caller_user,omitempty"` // Since: Bot API 10.0
-
+	GuestBotCallerChat     *Chat  `json:"guest_bot_caller_chat,omitempty"` // Since: Bot API 10.0
-	Date     int `json:"date"`
+	EditDate               int    `json:"edit_date,omitempty"`             // Since: Bot API 2.1
-	EditDate int `json:"edit_date"`
+	HasProtectedContent    bool   `json:"has_protected_content,omitempty"` // Since: Bot API 5.5
-
+	IsFromOffline          bool   `json:"is_from_offline,omitempty"`       // Since: Bot API 7.2
-	ReplyMarkup *MessageReplyMarkup `json:"reply_markup,omitempty"`
+	IsPaidPost             bool   `json:"is_paid_post,omitempty"`          // Since: Bot API 9.1
+	MediaGroupID           string `json:"media_group_id,omitempty"`        // Since: Bot API 3.5
+	AuthorSignature        string `json:"author_signature,omitempty"`
+	PaidStarCount          int    `json:"paid_star_count,omitempty"` // Since: Bot API 8.3
 
+	Text               string              `json:"text"`
 	Entities           []MessageEntity     `json:"entities,omitempty"`
 	LinkPreviewOptions *LinkPreviewOptions `json:"link_preview_options,omitempty"`
-	SuggestedPostInfo  *SuggestedPostInfo  `json:"suggested_post_info,omitempty"`
+	SuggestedPostInfo  *SuggestedPostInfo  `json:"suggested_post_info,omitempty"` // Since: Bot API 9.1
+	EffectID           string              `json:"effect_id,omitempty"`           // Since: Bot API 7.4
 
-	EffectID string `json:"effect_id,omitempty"`
+	Animation             *Animation               `json:"animation,omitempty"` // Since: Bot API 4.0
+	Audio                 *Audio                   `json:"audio,omitempty"`
+	Document              *Document                `json:"document,omitempty"`
+	PaidMedia             *PaidMediaInfo           `json:"paid_media,omitempty"` // Since: Bot API 7.6
+	Photo                 extypes.Slice[PhotoSize] `json:"photo,omitempty"`
+	LivePhoto             *LivePhoto               `json:"live_photo,omitempty"` // Since: Bot API 10.0
+	Sticker               *Sticker                 `json:"sticker,omitempty"`
+	Story                 *Story                   `json:"story,omitempty"`
+	Video                 *Video                   `json:"video,omitempty"`
+	VideoNote             *VideoNote               `json:"video_note,omitempty"`               // Since: Bot API 3.0
+	Voice                 *Voice                   `json:"voice,omitempty"`                    // Since: Bot API 1.2
+	Caption               string                   `json:"caption,omitempty"`                  // Since: Bot API 3.4
+	CaptionEntities       []MessageEntity          `json:"caption_entities,omitempty"`         // Since: Bot API 3.4
+	ShowCaptionAboveMedia bool                     `json:"show_caption_above_media,omitempty"` // Since: Bot API 7.4
+	HasMediaSpoiler       bool                     `json:"has_media_spoiler,omitempty"`        // Since: Bot API 6.4
+	Checklist             *Checklist               `json:"checklist,omitempty"`                // Since: Bot API 9.1
+	Contact               *Contact                 `json:"contact,omitempty"`
+	Dice                  *Dice                    `json:"dice,omitempty"`
+	Game                  *Game                    `json:"game,omitempty"`
+	Poll                  *Poll                    `json:"poll,omitempty"`
+	Venue                 *Venue                   `json:"venue,omitempty"`
+	Location              *Location                `json:"location,omitempty"`
+
+	NewChatMembers                []User                         `json:"new_chat_members,omitempty"`
+	LeftChatMember                *User                          `json:"left_chat_member,omitempty"`
+	ChatOwnerLeft                 *ChatOwnerLeft                 `json:"chat_owner_left,omitempty"`
+	ChatOwnerChanged              *ChatOwnerChanged              `json:"chat_owner_changed,omitempty"`
+	NewChatTitle                  string                         `json:"new_chat_title,omitempty"`
+	NewChatPhoto                  []PhotoSize                    `json:"new_chat_photo,omitempty"`
+	DeleteChatPhoto               bool                           `json:"delete_chat_photo,omitempty"`
+	GroupChatCreated              bool                           `json:"group_chat_created,omitempty"`
+	SupergroupChatCreated         bool                           `json:"supergroup_chat_created,omitempty"`
+	ChannelChatCreated            bool                           `json:"channel_chat_created,omitempty"`
+	MessageAutoDeleteTimerChanged *MessageAutoDeleteTimerChanged `json:"message_auto_delete_timer_changed,omitempty"` // Since: Bot API 5.1
+	MigrateToChatID               int64                          `json:"migrate_to_chat_id,omitempty"`
+	MigrateFromChatID             int64                          `json:"migrate_from_chat_id,omitempty"`
+	PinnedMessage                 *MaybeInaccessibleMessage      `json:"pinned_message,omitempty"`
+
+	Invoice           *Invoice           `json:"invoice,omitempty"`            // Since: Bot API 3.0
+	SuccessfulPayment *SuccessfulPayment `json:"successful_payment,omitempty"` // Since: Bot API 3.0
+	RefundedPayment   *RefundedPayment   `json:"refunded_payment,omitempty"`   // Since: Bot API 7.7
+	UsersShared       *UsersShared       `json:"users_shared,omitempty"`       // Since: Bot API 6.5
+	ChatShared        *ChatShared        `json:"chat_shared,omitempty"`        // Since: Bot API 6.5
+	Gift              *GiftInfo          `json:"gift,omitempty"`               // Since: Bot API 9.0
+	UniqueGift        *UniqueGiftInfo    `json:"unique_gift,omitempty"`        // Since: Bot API 9.0
+	GiftUpgradeSent   *GiftInfo          `json:"gift_upgrade_sent,omitempty"`  // Since: Bot API 9.3
+
+	ConnectedWebsite        string                   `json:"connected_website,omitempty"`
+	WriteAccessAllowed      *WriteAccessAllowed      `json:"write_access_allowed,omitempty"` // Since: Bot API 6.4
+	PassportData            *PassportData            `json:"passport_data,omitempty"`
+	ProximityAlertTriggered *ProximityAlertTriggered `json:"proximity_alert_triggered,omitempty"` // Since: Bot API 5.0
+	BoostAdded              *ChatBoostAdded          `json:"boost_added,omitempty"`               // Since: Bot API 7.1
+	ChatBackgroundSet       *ChatBackground          `json:"chat_background_set,omitempty"`       // Since: Bot API 7.5
+
+	ChecklistTaskDone         *ChecklistTaskDone         `json:"checklist_task_done,omitempty"`          // Since: Bot API 9.1
+	ChecklistTasksAdded       *ChecklistTasksAdded       `json:"checklist_tasks_added,omitempty"`        // Since: Bot API 9.1
+	DirectMessagePriceChanged *DirectMessagePriceChanged `json:"direct_message_price_changed,omitempty"` // Since: Bot API 9.1
+	PaidMessagePriceChanged   *PaidMessagePriceChanged   `json:"paid_message_price_changed,omitempty"`   // Since: Bot API 9.x
+	ForumTopicCreated         *ForumTopicCreated         `json:"forum_topic_created,omitempty"`          // Since: Bot API 6.3
+	ForumTopicEdited          *ForumTopicEdited          `json:"forum_topic_edited,omitempty"`           // Since: Bot API 6.4
+	ForumTopicClosed          *ForumTopicClosed          `json:"forum_topic_closed,omitempty"`           // Since: Bot API 6.3
+	ForumTopicReopened        *ForumTopicReopened        `json:"forum_topic_reopened,omitempty"`         // Since: Bot API 6.3
+	GeneralForumTopicHidden   *GeneralForumTopicHidden   `json:"general_forum_topic_hidden,omitempty"`   // Since: Bot API 6.4
+	GeneralForumTopicUnhidden *GeneralForumTopicUnhidden `json:"general_forum_topic_unhidden,omitempty"` // Since: Bot API 6.4
+
+	GiveawayCreated   *GiveawayCreated   `json:"giveaway_created,omitempty"`   // Since: Bot API 7.0
+	Giveaway          *Giveaway          `json:"giveaway,omitempty"`           // Since: Bot API 7.0
+	GiveawayWinners   *GiveawayWinners   `json:"giveaway_winners,omitempty"`   // Since: Bot API 7.0
+	GiveawayCompleted *GiveawayCompleted `json:"giveaway_completed,omitempty"` // Since: Bot API 7.0
+
+	ManagedBotCreated *ManagedBotCreated `json:"managed_bot_created,omitempty"` // Since: Bot API 9.6
+	PollOptionAdded   *PollOptionAdded   `json:"poll_option_added,omitempty"`   // Since: Bot API 9.6
+	PollOptionDeleted *PollOptionDeleted `json:"poll_option_deleted,omitempty"` // Since: Bot API 9.6
+
+	SuggestedPostApproved       *SuggestedPostApproved       `json:"suggested_post_approved,omitempty"`        // Since: Bot API 9.1
+	SuggestedPostApprovalFailed *SuggestedPostApprovalFailed `json:"suggested_post_approval_failed,omitempty"` // Since: Bot API 9.1
+	SuggestedPostDeclined       *SuggestedPostDeclined       `json:"suggested_post_declined,omitempty"`        // Since: Bot API 9.1
+	SuggestedPostPaid           *SuggestedPostPaid           `json:"suggested_post_paid,omitempty"`            // Since: Bot API 9.1
+	SuggestedPostRefunded       *SuggestedPostRefunded       `json:"suggested_post_refunded,omitempty"`        // Since: Bot API 9.1
+
+	VideoChatScheduled           *VideoChatScheduled           `json:"video_chat_scheduled,omitempty"`            // Since: Bot API 6.0
+	VideoChatStarted             *VideoChatStarted             `json:"video_chat_started,omitempty"`              // Since: Bot API 5.1
+	VideoChatEnded               *VideoChatEnded               `json:"video_chat_ended,omitempty"`                // Since: Bot API 5.1
+	VideoChatParticipantsInvited *VideoChatParticipantsInvited `json:"video_chat_participants_invited,omitempty"` // Since: Bot API 5.1
+
+	WebAppData  *WebAppData           `json:"web_app_data,omitempty"` // Since: Bot API 6.0
+	ReplyMarkup *InlineKeyboardMarkup `json:"reply_markup,omitempty"` // Since: Bot API 4.3
 }
 
 // InaccessibleMessage describes a message that was deleted or is otherwise inaccessible.
+// Since: Bot API 7.0
 // See https://core.telegram.org/bots/api#inaccessiblemessage
 type InaccessibleMessage struct {
 	Chat      Chat `json:"chat"`
@@ -70,8 +250,82 @@ type InaccessibleMessage struct {
 }
 
 // MaybeInaccessibleMessage is a union type that can be either Message or InaccessibleMessage.
+// Since: Bot API 7.0
 // See https://core.telegram.org/bots/api#maybeinaccessiblemessage
-type MaybeInaccessibleMessage interface{ Message | InaccessibleMessage }
+type MaybeInaccessibleMessage struct {
+	msg *Message
+	ina *InaccessibleMessage
+}
+
+// UnmarshalJSON decodes either an accessible Message or an InaccessibleMessage.
+func (m *MaybeInaccessibleMessage) UnmarshalJSON(data []byte) error {
+	tmp := struct {
+		Date int `json:"date"`
+	}{}
+	if err := json.Unmarshal(data, &tmp); err != nil {
+		return err
+	}
+	var err error
+	if tmp.Date > 0 {
+		err = json.Unmarshal(data, &m.msg)
+	} else {
+		err = json.Unmarshal(data, &m.ina)
+	}
+	if err != nil {
+		return err
+	}
+	return nil
+}
+
+// MarshalJSON encodes the populated accessible or inaccessible message payload.
+func (m *MaybeInaccessibleMessage) MarshalJSON() ([]byte, error) {
+	if m.msg != nil {
+		return json.Marshal(m.msg)
+	} else if m.ina != nil {
+		return json.Marshal(m.ina)
+	}
+	return json.Marshal(nil)
+}
+
+// Message returns the accessible message payload when present.
+func (m *MaybeInaccessibleMessage) Message() *Message {
+	return m.msg
+}
+
+// InaccessibleMessage returns the inaccessible message payload when present.
+func (m *MaybeInaccessibleMessage) InaccessibleMessage() *InaccessibleMessage {
+	return m.ina
+}
+
+// IsAccessible reports whether the payload is an accessible message.
+func (m *MaybeInaccessibleMessage) IsAccessible() bool {
+	return m.msg != nil
+}
+
+// IsInaccessible reports whether the payload is an inaccessible message.
+func (m *MaybeInaccessibleMessage) IsInaccessible() bool {
+	return m.ina != nil
+}
+
+// MessageID returns the message identifier from either payload form.
+func (m *MaybeInaccessibleMessage) MessageID() int {
+	if m.IsAccessible() {
+		return m.msg.MessageID
+	} else if m.IsInaccessible() {
+		return m.ina.MessageID
+	}
+	return 0
+}
+
+// Chat returns the chat from either payload form.
+func (m *MaybeInaccessibleMessage) Chat() *Chat {
+	if m.IsAccessible() {
+		return m.msg.Chat
+	} else if m.IsInaccessible() {
+		return &m.ina.Chat
+	}
+	return nil
+}
 
 // MessageEntityType represents the type of a message entity.
 type MessageEntityType string
@@ -85,8 +339,8 @@ const (
 	MessageEntityCashtag MessageEntityType = "cashtag"
 	// MessageEntityBotCommand identifies a bot command entity.
 	MessageEntityBotCommand MessageEntityType = "bot_command"
-	// MessageEntityUrl identifies a URL entity.
+	// MessageEntityURL identifies a URL entity.
-	MessageEntityUrl MessageEntityType = "url"
+	MessageEntityURL MessageEntityType = "url"
 	// MessageEntityEmail identifies an email entity.
 	MessageEntityEmail MessageEntityType = "email"
 	// MessageEntityPhoneNumber identifies a phone number entity.
@@ -100,11 +354,11 @@ const (
 	// MessageEntityStrike identifies strikethrough text.
 	MessageEntityStrike MessageEntityType = "strikethrough"
 	// MessageEntitySpoiler identifies spoiler text.
-	MessageEntitySpoiler MessageEntityType = "spoiler"
+	MessageEntitySpoiler MessageEntityType = "spoiler" // Since: Bot API 5.6
 	// MessageEntityBlockquote identifies a blockquote entity.
 	MessageEntityBlockquote MessageEntityType = "blockquote"
 	// MessageEntityExpandableBlockquote identifies an expandable blockquote entity.
-	MessageEntityExpandableBlockquote MessageEntityType = "expandable_blockquote"
+	MessageEntityExpandableBlockquote MessageEntityType = "expandable_blockquote" // Since: Bot API 7.5
 	// MessageEntityCode identifies inline code.
 	MessageEntityCode MessageEntityType = "code"
 	// MessageEntityPre identifies a preformatted block.
@@ -114,12 +368,13 @@ const (
 	// MessageEntityTextMention identifies a text mention.
 	MessageEntityTextMention MessageEntityType = "text_mention"
 	// MessageEntityCustomEmoji identifies a custom emoji entity.
-	MessageEntityCustomEmoji MessageEntityType = "custom_emoji"
+	MessageEntityCustomEmoji MessageEntityType = "custom_emoji" // Since: Bot API 6.2
 	// MessageEntityDateTime identifies a date-time entity.
-	MessageEntityDateTime MessageEntityType = "date_time"
+	MessageEntityDateTime MessageEntityType = "date_time" // Since: Bot API 9.5
 )
 
 // MessageEntity represents one special entity in a text message.
+// Since: Bot API 2.0
 // See https://core.telegram.org/bots/api#messageentity
 type MessageEntity struct {
 	Type MessageEntityType `json:"type"`
@@ -129,13 +384,14 @@ type MessageEntity struct {
 	URL           string `json:"url,omitempty"`
 	User          *User  `json:"user,omitempty"`
 	Language      string `json:"language,omitempty"`
-	CustomEmojiID string `json:"custom_emoji_id,omitempty"`
+	CustomEmojiID string `json:"custom_emoji_id,omitempty"` // Since: Bot API 6.2
 
-	UnixTime       int    `json:"unix_time,omitempty"`
+	UnixTime       int64  `json:"unix_time,omitempty"`
-	DateTimeFormat string `json:"date_time_format,omitempty"`
+	DateTimeFormat string `json:"date_time_format,omitempty"` // Since: Bot API 9.5
 }
 
 // ReplyParameters describes the parameters to use when replying to a message.
+// Since: Bot API 7.0
 // See https://core.telegram.org/bots/api#replyparameters
 type ReplyParameters struct {
 	MessageID int   `json:"message_id"`
@@ -147,9 +403,11 @@ type ReplyParameters struct {
 	QuoteEntities            []MessageEntity `json:"quote_entities,omitempty"`
 	QuotePosition            int             `json:"quote_position,omitempty"`
 	ChecklistTaskID          int             `json:"checklist_task_id,omitempty"`
+	PollOptionID             string          `json:"poll_option_id,omitempty"`
 }
 
 // LinkPreviewOptions describes the options used for link preview generation.
+// Since: Bot API 7.0
 // See https://core.telegram.org/bots/api#linkpreviewoptions
 type LinkPreviewOptions struct {
 	IsDisabled       bool   `json:"is_disabled,omitempty"`
@@ -160,6 +418,7 @@ type LinkPreviewOptions struct {
 }
 
 // ReplyMarkup represents a custom keyboard or inline keyboard.
+// Since: Bot API 1.0
 // See https://core.telegram.org/bots/api#replymarkup
 type ReplyMarkup struct {
 	InlineKeyboard [][]InlineKeyboardButton `json:"inline_keyboard,omitempty"`
@@ -177,6 +436,7 @@ type ReplyMarkup struct {
 }
 
 // InlineKeyboardMarkup represents an inline keyboard that appears right next to the message it belongs to.
+// Since: Bot API 2.0
 // See https://core.telegram.org/bots/api#inlinekeyboardmarkup
 type InlineKeyboardMarkup struct {
 	InlineKeyboard [][]InlineKeyboardButton `json:"inline_keyboard,omitempty"`
@@ -195,20 +455,23 @@ const (
 )
 
 // KeyboardButton represents one button of the reply keyboard.
+// Since: Bot API 2.0
 // See https://core.telegram.org/bots/api#keyboardbutton
 type KeyboardButton struct {
-	Text              string                      `json:"text"`
+	Text              string                           `json:"text"`
-	IconCustomEmojiID string                      `json:"icon_custom_emoji_id,omitempty"`
+	IconCustomEmojiID string                           `json:"icon_custom_emoji_id,omitempty"` // Since: Bot API 9.4
-	Style             KeyboardButtonStyle         `json:"style,omitempty"`
+	Style             KeyboardButtonStyle              `json:"style,omitempty"`                // Since: Bot API 9.4
-	RequestUsers      *KeyboardButtonRequestUsers `json:"request_users,omitempty"`
+	RequestUsers      *KeyboardButtonRequestUsers      `json:"request_users,omitempty"`        // Since: Bot API 7.0
-	RequestChat       *KeyboardButtonRequestChat  `json:"request_chat,omitempty"`
+	RequestChat       *KeyboardButtonRequestChat       `json:"request_chat,omitempty"`         // Since: Bot API 6.5
-	RequestContact    bool                        `json:"request_contact,omitempty"`
+	RequestManagedBot *KeyboardButtonRequestManagedBot `json:"request_managed_bot,omitempty"`  // Since: Bot API 9.6
-	RequestLocation   bool                        `json:"request_location,omitempty"`
+	RequestContact    bool                             `json:"request_contact,omitempty"`
-	RequestPoll       *KeyboardButtonPollType     `json:"request_poll,omitempty"`
+	RequestLocation   bool                             `json:"request_location,omitempty"`
-	WebApp            *WebAppInfo                 `json:"web_app,omitempty"`
+	RequestPoll       *KeyboardButtonPollType          `json:"request_poll,omitempty"` // Since: Bot API 4.6
+	WebApp            *WebAppInfo                      `json:"web_app,omitempty"`      // Since: Bot API 6.0
 }
 
 // KeyboardButtonRequestUsers defines criteria used to request suitable users.
+// Since: Bot API 7.0
 // See https://core.telegram.org/bots/api#keyboardbuttonrequestusers
 type KeyboardButtonRequestUsers struct {
 	RequestID       int   `json:"request_id"`
@@ -221,6 +484,7 @@ type KeyboardButtonRequestUsers struct {
 }
 
 // KeyboardButtonRequestChat defines criteria used to request a suitable chat.
+// Since: Bot API 6.5
 // See https://core.telegram.org/bots/api#keyboardbuttonrequestchat
 type KeyboardButtonRequestChat struct {
 	RequestID               int                      `json:"request_id"`
@@ -236,23 +500,35 @@ type KeyboardButtonRequestChat struct {
 	RequestPhoto            bool                     `json:"request_photo,omitempty"`
 }
 
+// KeyboardButtonRequestManagedBot defines criteria used to request a managed bot.
+// Since: Bot API 9.6
+// See https://core.telegram.org/bots/api#keyboardbuttonrequestmanagedbot
+type KeyboardButtonRequestManagedBot struct {
+	RequestID         int32  `json:"request_id"`
+	SuggestedName     string `json:"suggested_name,omitempty"`
+	SuggestedUsername string `json:"suggested_username,omitempty"`
+}
+
 // KeyboardButtonPollType represents the type of a poll that may be created from a keyboard button.
+// Since: Bot API 4.6
 // See https://core.telegram.org/bots/api#keyboardbuttonpolltype
 type KeyboardButtonPollType struct {
 	Type PollType `json:"type,omitempty"`
 }
 
 // InlineKeyboardButton represents one button of an inline keyboard.
+// Since: Bot API 2.0
 // See https://core.telegram.org/bots/api#inlinekeyboardbutton
 type InlineKeyboardButton struct {
 	Text              string              `json:"text"`
 	URL               string              `json:"url,omitempty"`
 	CallbackData      string              `json:"callback_data,omitempty"`
-	Style             KeyboardButtonStyle `json:"style,omitempty"`
+	Style             KeyboardButtonStyle `json:"style,omitempty"`                // Since: Bot API 9.4
-	IconCustomEmojiID string              `json:"icon_custom_emoji_id,omitempty"`
+	IconCustomEmojiID string              `json:"icon_custom_emoji_id,omitempty"` // Since: Bot API 9.4
 }
 
 // ReplyKeyboardMarkup represents a custom keyboard with reply options.
+// Since: Bot API 1.0
 // See https://core.telegram.org/bots/api#replykeyboardmarkup
 type ReplyKeyboardMarkup struct {
 	Keyboard              [][]KeyboardButton `json:"keyboard"`
@@ -264,6 +540,7 @@ type ReplyKeyboardMarkup struct {
 }
 
 // CallbackQuery represents an incoming callback query from a callback button in an inline keyboard.
+// Since: Bot API 2.0
 // See https://core.telegram.org/bots/api#callbackquery
 type CallbackQuery struct {
 	ID              string   `json:"id"`
@@ -275,42 +552,6 @@ type CallbackQuery struct {
 	GameShortName   string   `json:"game_short_name,omitempty"`
 }
 
-// InputPollOption contains information about one answer option in a poll to be sent.
-// See https://core.telegram.org/bots/api#inputpolloption
-type InputPollOption struct {
-	Text          string          `json:"text"`
-	TextParseMode ParseMode       `json:"text_parse_mode,omitempty"`
-	TextEntities  []MessageEntity `json:"text_entities,omitempty"`
-}
-
-// PollType represents the type of a poll.
-type PollType string
-
-const (
-	// PollTypeRegular identifies a regular poll.
-	PollTypeRegular PollType = "regular"
-	// PollTypeQuiz identifies a quiz poll.
-	PollTypeQuiz PollType = "quiz"
-)
-
-// InputChecklistTask describes a task in a checklist.
-type InputChecklistTask struct {
-	ID           int             `json:"id"`
-	Text         string          `json:"text"`
-	ParseMode    ParseMode       `json:"parse_mode,omitempty"`
-	TextEntities []MessageEntity `json:"text_entities,omitempty"`
-}
-
-// InputChecklist represents a checklist to be sent.
-type InputChecklist struct {
-	Title                   string               `json:"title"`
-	ParseMode               ParseMode            `json:"parse_mode,omitempty"`
-	TitleEntities           []MessageEntity      `json:"title_entities,omitempty"`
-	Tasks                   []InputChecklistTask `json:"tasks"`
-	OtherCanAddTasks        bool                 `json:"other_can_add_tasks,omitempty"`
-	OtherCanMarkTasksAsDone bool                 `json:"other_can_mark_tasks_as_done,omitempty"`
-}
-
 // ChatActionType represents the type of chat action.
 type ChatActionType string
 
@@ -332,10 +573,11 @@ const (
 	// ChatActionUploadVideoNote tells Telegram the bot is uploading a video note.
 	ChatActionUploadVideoNote ChatActionType = "upload_video_note"
 	// ChatActionUploadVideoNone is a deprecated alias for ChatActionUploadVideoNote.
-	ChatActionUploadVideoNone ChatActionType = ChatActionUploadVideoNote
+	ChatActionUploadVideoNone = ChatActionUploadVideoNote
 )
 
 // MessageReactionUpdated represents a change of a reaction on a message.
+// Since: Bot API 7.0
 // See https://core.telegram.org/bots/api#messagereactionupdated
 type MessageReactionUpdated struct {
 	Chat        *Chat          `json:"chat"`
@@ -348,6 +590,7 @@ type MessageReactionUpdated struct {
 }
 
 // MessageReactionCountUpdated represents a change in the count of reactions on a message.
+// Since: Bot API 7.0
 // See https://core.telegram.org/bots/api#messagereactioncountupdated
 type MessageReactionCountUpdated struct {
 	Chat      *Chat            `json:"chat"`
@@ -357,6 +600,7 @@ type MessageReactionCountUpdated struct {
 }
 
 // ReactionType describes the type of a reaction.
+// Since: Bot API 7.0
 // See https://core.telegram.org/bots/api#reactiontype
 type ReactionType struct {
 	Type string `json:"type"`
@@ -367,6 +611,7 @@ type ReactionType struct {
 }
 
 // ReactionCount represents a reaction added to a message along with the number of times it was added.
+// Since: Bot API 7.0
 // See https://core.telegram.org/bots/api#reactioncount
 type ReactionCount struct {
 	Type       ReactionType `json:"type"`
@@ -374,12 +619,14 @@ type ReactionCount struct {
 }
 
 // SuggestedPostPrice represents the price of a suggested post.
+// Since: Bot API 9.1
 type SuggestedPostPrice struct {
 	Currency string `json:"currency"`
 	Amount   int    `json:"amount"`
 }
 
 // SuggestedPostInfo contains information about a suggested post.
+// Since: Bot API 9.1
 // See https://core.telegram.org/bots/api#suggestedpostinfo
 type SuggestedPostInfo struct {
 	State    string             `json:"state"` // "pending", "approved", or "declined"
@@ -388,7 +635,116 @@ type SuggestedPostInfo struct {
 }
 
 // SuggestedPostParameters holds parameters for suggesting a post.
+// Since: Bot API 9.2
 type SuggestedPostParameters struct {
 	Price    SuggestedPostPrice `json:"price"`
 	SendDate int                `json:"send_date"`
 }
+
+// ManagedBotCreated describes a service message about a newly created managed bot.
+// Since: Bot API 9.6
+// See https://core.telegram.org/bots/api#managedbotcreated
+type ManagedBotCreated struct {
+	Bot User `json:"bot"`
+}
+
+// ManagedBotUpdated describes an update about a managed bot and its manager.
+// Since: Bot API 9.6
+// See https://core.telegram.org/bots/api#managedbotupdated
+type ManagedBotUpdated struct {
+	User User `json:"user"`
+	Bot  User `json:"bot"`
+}
+
+// SharedUser represents a user shared via a KeyboardButtonRequestUsers button.
+// Since: Bot API 7.2
+type SharedUser struct {
+	UserID    int64       `json:"user_id"`
+	FirstName string      `json:"first_name,omitempty"`
+	LastName  string      `json:"last_name,omitempty"`
+	Username  string      `json:"username,omitempty"`
+	Photo     []PhotoSize `json:"photo,omitempty"`
+}
+
+// UsersShared represents a service message about users shared via a KeyboardButtonRequestUsers button.
+// Since: Bot API 6.5
+type UsersShared struct {
+	RequestID int          `json:"request_id"`
+	Users     []SharedUser `json:"users"`
+}
+
+// ChatShared represents a service message about a chat shared via a KeyboardButtonRequestChat button.
+// Since: Bot API 6.5
+type ChatShared struct {
+	RequestID int         `json:"request_id"`
+	ChatID    int64       `json:"chat_id"`
+	Title     string      `json:"title,omitempty"`
+	Username  string      `json:"username,omitempty"`
+	Photo     []PhotoSize `json:"photo,omitempty"`
+}
+
+// SuggestedPostApproved is a service message about an approved suggested post.
+// Since: Bot API 9.1
+type SuggestedPostApproved struct {
+	SuggestedPostMessage *Message           `json:"suggested_post_message,omitempty"`
+	Price                SuggestedPostPrice `json:"price"`
+	SendDate             int                `json:"send_date"`
+}
+
+// SuggestedPostApprovalFailed is a service message about a failed suggested post approval.
+// Since: Bot API 9.1
+type SuggestedPostApprovalFailed struct {
+	SuggestedPostMessage *Message           `json:"suggested_post_message,omitempty"`
+	Price                SuggestedPostPrice `json:"price"`
+}
+
+// SuggestedPostDeclined is a service message about a declined suggested post.
+// Since: Bot API 9.1
+type SuggestedPostDeclined struct {
+	SuggestedPostMessage *Message `json:"suggested_post_message,omitempty"`
+	Comment              string   `json:"comment,omitempty"`
+}
+
+// SuggestedPostPaid is a service message about a paid suggested post.
+// Since: Bot API 9.1
+type SuggestedPostPaid struct {
+	SuggestedPostMessage *Message    `json:"suggested_post_message,omitempty"`
+	Currency             string      `json:"currency"`
+	Amount               int         `json:"amount"`
+	StarAmount           *StarAmount `json:"star_amount,omitempty"`
+}
+
+// SuggestedPostRefunded is a service message about a refunded suggested post.
+// Since: Bot API 9.1
+type SuggestedPostRefunded struct {
+	SuggestedPostMessage *Message `json:"suggested_post_message,omitempty"`
+	Reason               string   `json:"reason,omitempty"`
+}
+
+// VideoChatScheduled represents a service message about a video chat scheduled in the chat.
+// Since: Bot API 6.0
+type VideoChatScheduled struct {
+	StartDate int64 `json:"start_date"`
+}
+
+// VideoChatStarted represents a service message about a video chat started in the chat.
+// Since: Bot API 5.1
+type VideoChatStarted struct{}
+
+// VideoChatEnded represents a service message about a video chat ended in the chat.
+// Since: Bot API 5.1
+type VideoChatEnded struct {
+	Duration int64 `json:"duration"`
+}
+
+// VideoChatParticipantsInvited represents a service message about new members invited to a video chat.
+// Since: Bot API 5.1
+type VideoChatParticipantsInvited struct {
+	Users []User `json:"users"`
+}
+
+// SentGuestMessage describes an inline message sent by a guest bot.
+// Since: Bot API 10.0
+type SentGuestMessage struct {
+	InlineMessageID string `json:"inline_message_id"`
+}

tgapi/methods.go

@@ -6,7 +6,7 @@ import (
 	"io"
 	"net/http"
 
-	"git.nix13.pw/scuroneko/laniakea/utils"
+	"git.scuroneko.dev/scuroneko/laniakea/utils"
 )
 
 // UpdateParams holds parameters for the getUpdates method.
@@ -21,7 +21,7 @@ type UpdateParams struct {
 // GetMe returns basic information about the bot.
 // See https://core.telegram.org/bots/api#getme
 func (api *API) GetMe() (User, error) {
-	req := NewRequest[User, EmptyParams]("getMe", NoParams)
+	req := NewRequest[User]("getMe", NoParams)
 	return req.Do(api)
 }
 
@@ -29,7 +29,49 @@ func (api *API) GetMe() (User, error) {
 // It executes the same request but uses ctx for cancellation and deadlines.
 // See https://core.telegram.org/bots/api#getme
 func (api *API) GetMeWithContext(ctx context.Context) (User, error) {
-	req := NewRequest[User, EmptyParams]("getMe", NoParams)
+	req := NewRequest[User]("getMe", NoParams)
+	return req.DoWithContext(ctx, api)
+}
+
+// GetManagedBotToken holds parameters for the getManagedBotToken method.
+// See https://core.telegram.org/bots/api#getmanagedbottoken
+type GetManagedBotToken struct {
+	UserID int64 `json:"user_id"`
+}
+
+// GetManagedBotToken returns the current token of a managed bot.
+// See https://core.telegram.org/bots/api#getmanagedbottoken
+func (api *API) GetManagedBotToken(params GetManagedBotToken) (string, error) {
+	req := NewRequest[string]("getManagedBotToken", params)
+	return req.Do(api)
+}
+
+// GetManagedBotTokenWithContext is the context-aware variant of GetManagedBotToken.
+// It executes the same request but uses ctx for cancellation and deadlines.
+// See https://core.telegram.org/bots/api#getmanagedbottoken
+func (api *API) GetManagedBotTokenWithContext(ctx context.Context, params GetManagedBotToken) (string, error) {
+	req := NewRequest[string]("getManagedBotToken", params)
+	return req.DoWithContext(ctx, api)
+}
+
+// ReplaceManagedBotToken holds parameters for the replaceManagedBotToken method.
+// See https://core.telegram.org/bots/api#replacemanagedbottoken
+type ReplaceManagedBotToken struct {
+	UserID int64 `json:"user_id"`
+}
+
+// ReplaceManagedBotToken replaces and returns the token of a managed bot.
+// See https://core.telegram.org/bots/api#replacemanagedbottoken
+func (api *API) ReplaceManagedBotToken(params ReplaceManagedBotToken) (string, error) {
+	req := NewRequest[string]("replaceManagedBotToken", params)
+	return req.Do(api)
+}
+
+// ReplaceManagedBotTokenWithContext is the context-aware variant of ReplaceManagedBotToken.
+// It executes the same request but uses ctx for cancellation and deadlines.
+// See https://core.telegram.org/bots/api#replacemanagedbottoken
+func (api *API) ReplaceManagedBotTokenWithContext(ctx context.Context, params ReplaceManagedBotToken) (string, error) {
+	req := NewRequest[string]("replaceManagedBotToken", params)
 	return req.DoWithContext(ctx, api)
 }
 
@@ -80,13 +122,13 @@ func (api *API) GetUpdatesWithContext(ctx context.Context, params UpdateParams)
 	return req.DoWithContext(ctx, api)
 }
 
-// SetWebhookP holds parameters for the setWebhook method.
+// SetWebhook holds parameters for the setWebhook method.
 // To upload a self-signed certificate, use Uploader.SetWebhook.
 // See https://core.telegram.org/bots/api#setwebhook
-type SetWebhookP struct {
+type SetWebhook struct {
 	URL                string       `json:"url"`
 	IPAddress          string       `json:"ip_address,omitempty"`
-	MaxConnections     int          `json:"max_connections,omitempty"`
+	MaxConnections     int8         `json:"max_connections,omitempty"`
 	AllowedUpdates     []UpdateType `json:"allowed_updates,omitempty"`
 	DropPendingUpdates bool         `json:"drop_pending_updates,omitempty"`
 	SecretToken        string       `json:"secret_token,omitempty"`
@@ -96,7 +138,7 @@ type SetWebhookP struct {
 // For certificate upload, use Uploader.SetWebhook.
 // Returns true on success.
 // See https://core.telegram.org/bots/api#setwebhook
-func (api *API) SetWebhook(params SetWebhookP) (bool, error) {
+func (api *API) SetWebhook(params SetWebhook) (bool, error) {
 	req := NewRequest[bool]("setWebhook", params)
 	return req.Do(api)
 }
@@ -105,21 +147,21 @@ func (api *API) SetWebhook(params SetWebhookP) (bool, error) {
 // It executes the same request but uses ctx for cancellation and deadlines.
 // For certificate upload, use Uploader.SetWebhook.
 // See https://core.telegram.org/bots/api#setwebhook
-func (api *API) SetWebhookWithContext(ctx context.Context, params SetWebhookP) (bool, error) {
+func (api *API) SetWebhookWithContext(ctx context.Context, params SetWebhook) (bool, error) {
 	req := NewRequest[bool]("setWebhook", params)
 	return req.DoWithContext(ctx, api)
 }
 
-// DeleteWebhookP holds parameters for the deleteWebhook method.
+// DeleteWebhook holds parameters for the deleteWebhook method.
 // See https://core.telegram.org/bots/api#deletewebhook
-type DeleteWebhookP struct {
+type DeleteWebhook struct {
 	DropPendingUpdates bool `json:"drop_pending_updates,omitempty"`
 }
 
 // DeleteWebhook removes the current webhook integration.
 // Returns true on success.
 // See https://core.telegram.org/bots/api#deletewebhook
-func (api *API) DeleteWebhook(params DeleteWebhookP) (bool, error) {
+func (api *API) DeleteWebhook(params DeleteWebhook) (bool, error) {
 	req := NewRequest[bool]("deleteWebhook", params)
 	return req.Do(api)
 }
@@ -127,7 +169,7 @@ func (api *API) DeleteWebhook(params DeleteWebhookP) (bool, error) {
 // DeleteWebhookWithContext is the context-aware variant of DeleteWebhook.
 // It executes the same request but uses ctx for cancellation and deadlines.
 // See https://core.telegram.org/bots/api#deletewebhook
-func (api *API) DeleteWebhookWithContext(ctx context.Context, params DeleteWebhookP) (bool, error) {
+func (api *API) DeleteWebhookWithContext(ctx context.Context, params DeleteWebhook) (bool, error) {
 	req := NewRequest[bool]("deleteWebhook", params)
 	return req.DoWithContext(ctx, api)
 }
@@ -147,15 +189,15 @@ func (api *API) GetWebhookInfoWithContext(ctx context.Context) (WebhookInfo, err
 	return req.DoWithContext(ctx, api)
 }
 
-// GetFileP holds parameters for the getFile method.
+// GetFile holds parameters for the getFile method.
 // See https://core.telegram.org/bots/api#getfile
-type GetFileP struct {
+type GetFile struct {
-	FileId string `json:"file_id"`
+	FileID string `json:"file_id"`
 }
 
 // GetFile returns basic information about a file and prepares it for downloading.
 // See https://core.telegram.org/bots/api#getfile
-func (api *API) GetFile(params GetFileP) (File, error) {
+func (api *API) GetFile(params GetFile) (File, error) {
 	req := NewRequest[File]("getFile", params)
 	return req.Do(api)
 }
@@ -163,7 +205,7 @@ func (api *API) GetFile(params GetFileP) (File, error) {
 // GetFileWithContext is the context-aware variant of GetFile.
 // It executes the same request but uses ctx for cancellation and deadlines.
 // See https://core.telegram.org/bots/api#getfile
-func (api *API) GetFileWithContext(ctx context.Context, params GetFileP) (File, error) {
+func (api *API) GetFileWithContext(ctx context.Context, params GetFile) (File, error) {
 	req := NewRequest[File]("getFile", params)
 	return req.DoWithContext(ctx, api)
 }
@@ -214,7 +256,7 @@ func (api *API) openFileByLink(ctx context.Context, link string) (io.ReadCloser,
 	if api.useTestServer {
 		methodPrefix = "/test"
 	}
-	u := fmt.Sprintf("%s/file/bot%s%s/%s", api.apiUrl, api.token, methodPrefix, link)
+	u := fmt.Sprintf("%s/file/bot%s%s/%s", api.apiURL, api.token, methodPrefix, link)
 
 	req, err := http.NewRequestWithContext(ctx, http.MethodGet, u, nil)
 	if err != nil {

tgapi/methods_test.go

@@ -23,7 +23,7 @@ func TestGetFileByLinkUsesConfiguredAPIURL(t *testing.T) {
 
 	api := NewAPI(
 		NewAPIOpts("token").
-			SetAPIUrl("https://example.test").
+			SetAPIURL("https://example.test").
 			SetHTTPClient(client),
 	)
 	defer func() {
@@ -47,7 +47,7 @@ func TestGetFileByLinkUsesConfiguredAPIURL(t *testing.T) {
 func TestOpenFileByLinkStreamsResponseBody(t *testing.T) {
 	api := NewAPI(
 		NewAPIOpts("token").
-			SetAPIUrl("https://example.test").
+			SetAPIURL("https://example.test").
 			SetHTTPClient(&http.Client{
 				Transport: roundTripFunc(func(req *http.Request) (*http.Response, error) {
 					return &http.Response{
@@ -94,7 +94,7 @@ func TestGetFileByLinkReturnsHTTPStatusError(t *testing.T) {
 
 	api := NewAPI(
 		NewAPIOpts("token").
-			SetAPIUrl("https://example.test").
+			SetAPIURL("https://example.test").
 			SetHTTPClient(client),
 	)
 	defer func() {
@@ -131,7 +131,7 @@ func TestGetUpdatesOmitsAllowedUpdatesWhenEmpty(t *testing.T) {
 
 	api := NewAPI(
 		NewAPIOpts("token").
-			SetAPIUrl("https://example.test").
+			SetAPIURL("https://example.test").
 			SetHTTPClient(client),
 	)
 	defer func() {
@@ -151,3 +151,60 @@ func TestGetUpdatesOmitsAllowedUpdatesWhenEmpty(t *testing.T) {
 		t.Fatalf("expected allowed_updates to be omitted, got %v", gotBody["allowed_updates"])
 	}
 }
+
+func TestSetChatMenuButtonSendsStructuredMenuButton(t *testing.T) {
+	var gotBody map[string]any
+
+	client := &http.Client{
+		Transport: roundTripFunc(func(req *http.Request) (*http.Response, error) {
+			body, err := io.ReadAll(req.Body)
+			if err != nil {
+				t.Fatalf("failed to read request body: %v", err)
+			}
+			if err := json.Unmarshal(body, &gotBody); err != nil {
+				t.Fatalf("failed to decode request body: %v", err)
+			}
+			return &http.Response{
+				StatusCode: http.StatusOK,
+				Header:     http.Header{"Content-Type": []string{"application/json"}},
+				Body:       io.NopCloser(strings.NewReader(`{"ok":true,"result":true}`)),
+			}, nil
+		}),
+	}
+
+	api := NewAPI(
+		NewAPIOpts("token").
+			SetAPIURL("https://example.test").
+			SetHTTPClient(client),
+	)
+	defer func() {
+		if err := api.Close(); err != nil {
+			t.Fatalf("Close returned error: %v", err)
+		}
+	}()
+
+	text := "Open"
+	if _, err := api.SetChatMenuButton(SetChatMenuButton{
+		ChatID: 42,
+		MenuButton: &MenuButton{
+			Type: MenuButtonWebAppType,
+			Text: &text,
+			WebApp: &WebAppInfo{
+				URL: "https://example.test/app",
+			},
+		},
+	}); err != nil {
+		t.Fatalf("SetChatMenuButton returned error: %v", err)
+	}
+
+	menuButton, ok := gotBody["menu_button"].(map[string]any)
+	if !ok {
+		t.Fatalf("expected structured menu_button, got %#v", gotBody["menu_button"])
+	}
+	if menuButton["type"] != string(MenuButtonWebAppType) {
+		t.Fatalf("unexpected menu button type: %#v", menuButton["type"])
+	}
+	if menuButton["text"] != text {
+		t.Fatalf("unexpected menu button text: %#v", menuButton["text"])
+	}
+}

tgapi/methods_types.go

@@ -4,12 +4,12 @@ package tgapi
 type ParseMode string
 
 const (
-	// ParseMDV2 enables MarkdownV2 style parsing.
+	// ParseMarkdownV2 enables MarkdownV2 style parsing.
-	ParseMDV2 ParseMode = "MarkdownV2"
+	ParseMarkdownV2 ParseMode = "MarkdownV2"
 	// ParseHTML enables HTML style parsing.
 	ParseHTML ParseMode = "HTML"
-	// ParseMD enables legacy Markdown style parsing.
+	// ParseMarkdown enables legacy Markdown style parsing.
-	ParseMD ParseMode = "Markdown"
+	ParseMarkdown ParseMode = "Markdown"
 	// ParseNone disables parse_mode and leaves plain-text requests unannotated.
 	ParseNone ParseMode = ""
 )
@@ -19,17 +19,3 @@ type EmptyParams struct{}
 
 // NoParams is a convenient instance of EmptyParams.
 var NoParams = EmptyParams{}
-
-// WebhookInfo describes the current webhook status.
-// See https://core.telegram.org/bots/api#webhookinfo
-type WebhookInfo struct {
-	URL                          string   `json:"url"`
-	HasCustomCertificate         bool     `json:"has_custom_certificate"`
-	PendingUpdateCount           int      `json:"pending_update_count"`
-	IPAddress                    string   `json:"ip_address,omitempty"`
-	LastErrorDate                int      `json:"last_error_date,omitempty"`
-	LastErrorMessage             string   `json:"last_error_message,omitempty"`
-	LastSynchronizationErrorDate int      `json:"last_synchronization_error_date,omitempty"`
-	MaxConnections               int      `json:"max_connections,omitempty"`
-	AllowedUpdates               []string `json:"allowed_updates,omitempty"`
-}

tgapi/parse_mode_test.go

@@ -7,7 +7,7 @@ import (
 )
 
 func TestParseNoneOmitsParseModeInJSON(t *testing.T) {
-	data, err := json.Marshal(SendMessageP{
+	data, err := json.Marshal(SendMessage{
 		ChatID:    42,
 		Text:      "hello",
 		ParseMode: ParseNone,
@@ -22,10 +22,10 @@ func TestParseNoneOmitsParseModeInJSON(t *testing.T) {
 }
 
 func TestParseModeStillSerializesExplicitModes(t *testing.T) {
-	data, err := json.Marshal(SendMessageP{
+	data, err := json.Marshal(SendMessage{
 		ChatID:    42,
 		Text:      "hello",
-		ParseMode: ParseMDV2,
+		ParseMode: ParseMarkdownV2,
 	})
 	if err != nil {
 		t.Fatalf("Marshal returned error: %v", err)

tgapi/passport_methods.go

@@ -2,25 +2,28 @@ package tgapi
 
 import "context"
 
-// SetPassportDataErrorsP holds parameters for the setPassportDataErrors method.
+// SetPassportDataErrors holds parameters for the setPassportDataErrors method.
+// Since: Bot API 4.0
 // See https://core.telegram.org/bots/api#setpassportdataerrors
-type SetPassportDataErrorsP struct {
+type SetPassportDataErrors struct {
 	UserID int64                  `json:"user_id"`
 	Errors []PassportElementError `json:"errors"`
 }
 
 // SetPassportDataErrors informs a user about Telegram Passport data errors.
+// Since: Bot API 4.0
 // Returns true on success.
 // See https://core.telegram.org/bots/api#setpassportdataerrors
-func (api *API) SetPassportDataErrors(params SetPassportDataErrorsP) (bool, error) {
+func (api *API) SetPassportDataErrors(params SetPassportDataErrors) (bool, error) {
 	req := NewRequest[bool]("setPassportDataErrors", params)
 	return req.Do(api)
 }
 
 // SetPassportDataErrorsWithContext is the context-aware variant of SetPassportDataErrors.
+// Since: Bot API 4.0
 // It executes the same request but uses ctx for cancellation and deadlines.
 // See https://core.telegram.org/bots/api#setpassportdataerrors
-func (api *API) SetPassportDataErrorsWithContext(ctx context.Context, params SetPassportDataErrorsP) (bool, error) {
+func (api *API) SetPassportDataErrorsWithContext(ctx context.Context, params SetPassportDataErrors) (bool, error) {
 	req := NewRequest[bool]("setPassportDataErrors", params)
 	return req.DoWithContext(ctx, api)
 }

tgapi/passport_types.go

@@ -1,5 +1,77 @@
 package tgapi
 
+// PassportData contains information about Telegram Passport data shared with the bot.
+// Since: Bot API 4.0
+type PassportData struct {
+	Data        []EncryptedPassportElement `json:"data"`
+	Credentials EncryptedCredentials       `json:"credentials"`
+}
+
+// PassportFile represents a file uploaded to Telegram Passport.
+// Since: Bot API 4.0
+type PassportFile struct {
+	FileID       string `json:"file_id"`
+	FileUniqueID string `json:"file_unique_id"`
+	FileSize     int64  `json:"file_size"`
+	FileDate     int64  `json:"file_date"`
+}
+
+// PassportElementType represents the type of a Telegram Passport element.
+type PassportElementType string
+
+const (
+	PassportPersonalDetailsType       PassportElementType = "personal_details"
+	PassportPassportType              PassportElementType = "passport"
+	PassportDriverLicenseType         PassportElementType = "driver_license"
+	PassportIdentityCardType          PassportElementType = "identity_card"
+	PassportInternalPassportType      PassportElementType = "internal_passport"
+	PassportAddressType               PassportElementType = "address"
+	PassportUtilityBillType           PassportElementType = "utility_bill"
+	PassportBankStatementType         PassportElementType = "bank_statement"
+	PassportRentalAgreementType       PassportElementType = "rental_agreement"
+	PassportPassportRegistrationType  PassportElementType = "passport_registration"
+	PassportTemporaryRegistrationType PassportElementType = "temporary_registration"
+	PassportPhoneNumberType           PassportElementType = "phone_number"
+	PassportEmailType                 PassportElementType = "email"
+)
+
+// EncryptedPassportElement contains information about documents or other Telegram Passport elements.
+// Since: Bot API 4.0
+type EncryptedPassportElement struct {
+	Type        PassportElementType `json:"type"`
+	Data        string              `json:"data,omitempty"`
+	PhoneNumber string              `json:"phone_number,omitempty"`
+	Email       string              `json:"email,omitempty"`
+	Files       []PassportFile      `json:"files,omitempty"`
+	FrontSide   *PassportFile       `json:"front_side,omitempty"`
+	ReverseSide *PassportFile       `json:"reverse_side,omitempty"`
+	Selfie      *PassportFile       `json:"selfie,omitempty"`
+	Translation *PassportFile       `json:"translation,omitempty"`
+	Hash        string              `json:"hash,omitempty"`
+}
+
+// EncryptedCredentials contains data required for decrypting and authenticating EncryptedPassportElement.
+// Since: Bot API 4.0
+type EncryptedCredentials struct {
+	Data   string `json:"data"`
+	Hash   string `json:"hash"`
+	Secret string `json:"secret"`
+}
+
 // PassportElementError is a JSON-serializable passport element error object.
+// Since: Bot API 4.0
 // See https://core.telegram.org/bots/api#passportelementerror
-type PassportElementError map[string]any
+type PassportElementError struct {
+	Source string              `json:"source"`
+	Type   PassportElementType `json:"type"`
+
+	FieldName string `json:"field_name,omitempty"`
+	DataHash  string `json:"data_hash,omitempty"`
+
+	FileHash   string   `json:"file_hash,omitempty"`
+	FileHashes []string `json:"file_hashes,omitempty"`
+
+	ElementHash string `json:"element_hash,omitempty"`
+
+	Message string `json:"message"`
+}

tgapi/payments_methods.go

@@ -2,9 +2,10 @@ package tgapi
 
 import "context"
 
-// SendInvoiceP holds parameters for the sendInvoice method.
+// SendInvoice holds parameters for the sendInvoice method.
+// Since: Bot API 3.0
 // See https://core.telegram.org/bots/api#sendinvoice
-type SendInvoiceP struct {
+type SendInvoice struct {
 	ChatID                int64 `json:"chat_id"`
 	MessageThreadID       int   `json:"message_thread_id,omitempty"`
 	DirectMessagesTopicID int   `json:"direct_messages_topic_id,omitempty"`
@@ -42,23 +43,26 @@ type SendInvoiceP struct {
 }
 
 // SendInvoice sends an invoice.
+// Since: Bot API 3.0
 // See https://core.telegram.org/bots/api#sendinvoice
-func (api *API) SendInvoice(params SendInvoiceP) (Message, error) {
+func (api *API) SendInvoice(params SendInvoice) (Message, error) {
 	req := NewRequestWithChatID[Message]("sendInvoice", params, params.ChatID)
 	return req.Do(api)
 }
 
 // SendInvoiceWithContext is the context-aware variant of SendInvoice.
+// Since: Bot API 3.0
 // It executes the same request but uses ctx for cancellation and deadlines.
 // See https://core.telegram.org/bots/api#sendinvoice
-func (api *API) SendInvoiceWithContext(ctx context.Context, params SendInvoiceP) (Message, error) {
+func (api *API) SendInvoiceWithContext(ctx context.Context, params SendInvoice) (Message, error) {
 	req := NewRequestWithChatID[Message]("sendInvoice", params, params.ChatID)
 	return req.DoWithContext(ctx, api)
 }
 
-// CreateInvoiceLinkP holds parameters for the createInvoiceLink method.
+// CreateInvoiceLink holds parameters for the createInvoiceLink method.
+// Since: Bot API 6.1
 // See https://core.telegram.org/bots/api#createinvoicelink
-type CreateInvoiceLinkP struct {
+type CreateInvoiceLink struct {
 	BusinessConnectionID string `json:"business_connection_id,omitempty"`
 
 	Title         string         `json:"title"`
@@ -86,23 +90,26 @@ type CreateInvoiceLinkP struct {
 }
 
 // CreateInvoiceLink creates an invoice link.
+// Since: Bot API 6.1
 // See https://core.telegram.org/bots/api#createinvoicelink
-func (api *API) CreateInvoiceLink(params CreateInvoiceLinkP) (string, error) {
+func (api *API) CreateInvoiceLink(params CreateInvoiceLink) (string, error) {
 	req := NewRequest[string]("createInvoiceLink", params)
 	return req.Do(api)
 }
 
 // CreateInvoiceLinkWithContext is the context-aware variant of CreateInvoiceLink.
+// Since: Bot API 6.1
 // It executes the same request but uses ctx for cancellation and deadlines.
 // See https://core.telegram.org/bots/api#createinvoicelink
-func (api *API) CreateInvoiceLinkWithContext(ctx context.Context, params CreateInvoiceLinkP) (string, error) {
+func (api *API) CreateInvoiceLinkWithContext(ctx context.Context, params CreateInvoiceLink) (string, error) {
 	req := NewRequest[string]("createInvoiceLink", params)
 	return req.DoWithContext(ctx, api)
 }
 
-// AnswerShippingQueryP holds parameters for the answerShippingQuery method.
+// AnswerShippingQuery holds parameters for the answerShippingQuery method.
+// Since: Bot API 3.0
 // See https://core.telegram.org/bots/api#answershippingquery
-type AnswerShippingQueryP struct {
+type AnswerShippingQuery struct {
 	ShippingQueryID string           `json:"shipping_query_id"`
 	OK              bool             `json:"ok"`
 	ShippingOptions []ShippingOption `json:"shipping_options,omitempty"`
@@ -110,41 +117,46 @@ type AnswerShippingQueryP struct {
 }
 
 // AnswerShippingQuery answers a shipping query.
+// Since: Bot API 3.0
 // Returns true on success.
 // See https://core.telegram.org/bots/api#answershippingquery
-func (api *API) AnswerShippingQuery(params AnswerShippingQueryP) (bool, error) {
+func (api *API) AnswerShippingQuery(params AnswerShippingQuery) (bool, error) {
 	req := NewRequest[bool]("answerShippingQuery", params)
 	return req.Do(api)
 }
 
 // AnswerShippingQueryWithContext is the context-aware variant of AnswerShippingQuery.
+// Since: Bot API 3.0
 // It executes the same request but uses ctx for cancellation and deadlines.
 // See https://core.telegram.org/bots/api#answershippingquery
-func (api *API) AnswerShippingQueryWithContext(ctx context.Context, params AnswerShippingQueryP) (bool, error) {
+func (api *API) AnswerShippingQueryWithContext(ctx context.Context, params AnswerShippingQuery) (bool, error) {
 	req := NewRequest[bool]("answerShippingQuery", params)
 	return req.DoWithContext(ctx, api)
 }
 
-// AnswerPreCheckoutQueryP holds parameters for the answerPreCheckoutQuery method.
+// AnswerPreCheckoutQuery holds parameters for the answerPreCheckoutQuery method.
+// Since: Bot API 3.0
 // See https://core.telegram.org/bots/api#answerprecheckoutquery
-type AnswerPreCheckoutQueryP struct {
+type AnswerPreCheckoutQuery struct {
 	PreCheckoutQueryID string `json:"pre_checkout_query_id"`
 	OK                 bool   `json:"ok"`
 	ErrorMessage       string `json:"error_message,omitempty"`
 }
 
 // AnswerPreCheckoutQuery answers a pre-checkout query.
+// Since: Bot API 3.0
 // Returns true on success.
 // See https://core.telegram.org/bots/api#answerprecheckoutquery
-func (api *API) AnswerPreCheckoutQuery(params AnswerPreCheckoutQueryP) (bool, error) {
+func (api *API) AnswerPreCheckoutQuery(params AnswerPreCheckoutQuery) (bool, error) {
 	req := NewRequest[bool]("answerPreCheckoutQuery", params)
 	return req.Do(api)
 }
 
 // AnswerPreCheckoutQueryWithContext is the context-aware variant of AnswerPreCheckoutQuery.
+// Since: Bot API 3.0
 // It executes the same request but uses ctx for cancellation and deadlines.
 // See https://core.telegram.org/bots/api#answerprecheckoutquery
-func (api *API) AnswerPreCheckoutQueryWithContext(ctx context.Context, params AnswerPreCheckoutQueryP) (bool, error) {
+func (api *API) AnswerPreCheckoutQueryWithContext(ctx context.Context, params AnswerPreCheckoutQuery) (bool, error) {
 	req := NewRequest[bool]("answerPreCheckoutQuery", params)
 	return req.DoWithContext(ctx, api)
 }

tgapi/payments_types.go

@@ -1,16 +1,109 @@
 package tgapi
 
 // LabeledPrice represents a price portion.
+// Since: Bot API 3.0
 // See https://core.telegram.org/bots/api#labeledprice
 type LabeledPrice struct {
 	Label  string `json:"label"`
 	Amount int    `json:"amount"`
 }
 
+// Invoice contains basic information about an invoice.
+// Since: Bot API 3.0
+type Invoice struct {
+	Title          string `json:"title"`
+	Description    string `json:"description"`
+	StartParameter string `json:"start_parameter"`
+	Currency       string `json:"currency"`
+	TotalAmount    int    `json:"total_amount"`
+}
+
+// ShippingQuery represents an incoming shipping query.
+// Since: Bot API 3.0
+// See https://core.telegram.org/bots/api#shippingquery
+type ShippingQuery struct {
+	ID              string          `json:"id"`
+	From            User            `json:"from"`
+	InvoicePayload  string          `json:"invoice_payload"`
+	ShippingAddress ShippingAddress `json:"shipping_address"`
+}
+
+// ShippingAddress represents a shipping address.
+// Since: Bot API 3.0
+// See https://core.telegram.org/bots/api#shippingaddress
+type ShippingAddress struct {
+	CountryCode string `json:"country_code"`
+	State       string `json:"state"`
+	City        string `json:"city"`
+	StreetLine1 string `json:"street_line1"`
+	StreetLine2 string `json:"street_line2"`
+	PostCode    string `json:"post_code"`
+}
+
+// OrderInfo represents information about an order.
+// Since: Bot API 3.0
+// See https://core.telegram.org/bots/api#orderinfo
+type OrderInfo struct {
+	Name            string          `json:"name"`
+	PhoneNumber     string          `json:"phone_number"`
+	Email           string          `json:"email"`
+	ShippingAddress ShippingAddress `json:"shipping_address"`
+}
+
+// PreCheckoutQuery represents an incoming pre-checkout query.
+// Since: Bot API 3.0
+// See https://core.telegram.org/bots/api#precheckoutquery
+type PreCheckoutQuery struct {
+	ID               string     `json:"id"`
+	From             User       `json:"from"`
+	Currency         string     `json:"currency"`
+	TotalAmount      int        `json:"total_amount"`
+	InvoicePayload   string     `json:"invoice_payload"`
+	ShippingOptionID string     `json:"shipping_option_id"`
+	OrderInfo        *OrderInfo `json:"order_info,omitempty"`
+}
+
+// PaidMediaPurchased represents a purchased paid media.
+// Since: Bot API 7.10
+// See https://core.telegram.org/bots/api#paidmediapurchased
+type PaidMediaPurchased struct {
+	From             User   `json:"from"`
+	PaidMediaPayload string `json:"paid_media_payload"`
+}
+
 // ShippingOption represents one shipping option.
+// Since: Bot API 3.0
 // See https://core.telegram.org/bots/api#shippingoption
 type ShippingOption struct {
 	ID     string         `json:"id"`
 	Title  string         `json:"title"`
 	Prices []LabeledPrice `json:"prices"`
 }
+
+// SuccessfulPayment contains basic information about a successful payment.
+// Since: Bot API 3.0
+type SuccessfulPayment struct {
+	Currency       string `json:"currency"`
+	TotalAmount    int    `json:"total_amount"`
+	InvoicePayload string `json:"invoice_payload"`
+
+	SubscriptionExpirationDate int        `json:"subscription_expiration_date,omitempty"` // Since: Bot API 8.0
+	IsRecurring                bool       `json:"is_recurring,omitempty"`                 // Since: Bot API 8.0
+	IsFirstRecurring           bool       `json:"is_first_recurring,omitempty"`           // Since: Bot API 8.0
+	ShippingOptionID           string     `json:"shipping_option_id,omitempty"`
+	OrderInfo                  *OrderInfo `json:"order_info,omitempty"`
+
+	TelegramPaymentChargeID string `json:"telegram_payment_charge_id"`
+	ProviderPaymentChargeID string `json:"proviced_payment_charge_id"`
+}
+
+// RefundedPayment contains basic information about a refunded payment.
+// Since: Bot API 7.7
+type RefundedPayment struct {
+	Currency       string `json:"currency"`
+	TotalAmount    int    `json:"total_amount"`
+	InvoicePayload string `json:"invoice_payload"`
+
+	TelegramPaymentChargeID string `json:"telegram_payment_charge_id"`
+	ProviderPaymentChargeID string `json:"proviced_payment_charge_id,omitempty"`
+}

tgapi/stars_methods.go

@@ -2,14 +2,16 @@ package tgapi
 
 import "context"
 
-// GetStarTransactionsP holds parameters for the getStarTransactions method.
+// GetStarTransactions holds parameters for the getStarTransactions method.
+// Since: Bot API 7.5
 // See https://core.telegram.org/bots/api#getstartransactions
-type GetStarTransactionsP struct {
+type GetStarTransactions struct {
 	Offset int `json:"offset,omitempty"`
 	Limit  int `json:"limit,omitempty"`
 }
 
 // GetMyStarBalance returns the bot's Telegram Star balance.
+// Since: Bot API 7.5
 // See https://core.telegram.org/bots/api#getmystarbalance
 func (api *API) GetMyStarBalance() (StarAmount, error) {
 	req := NewRequest[StarAmount]("getMyStarBalance", NoParams)
@@ -17,6 +19,7 @@ func (api *API) GetMyStarBalance() (StarAmount, error) {
 }
 
 // GetMyStarBalanceWithContext is the context-aware variant of GetMyStarBalance.
+// Since: Bot API 7.5
 // It executes the same request but uses ctx for cancellation and deadlines.
 // See https://core.telegram.org/bots/api#getmystarbalance
 func (api *API) GetMyStarBalanceWithContext(ctx context.Context) (StarAmount, error) {
@@ -25,63 +28,71 @@ func (api *API) GetMyStarBalanceWithContext(ctx context.Context) (StarAmount, er
 }
 
 // GetStarTransactions returns Telegram Star transactions for the bot.
+// Since: Bot API 7.5
 // See https://core.telegram.org/bots/api#getstartransactions
-func (api *API) GetStarTransactions(params GetStarTransactionsP) (StarTransactions, error) {
+func (api *API) GetStarTransactions(params GetStarTransactions) (StarTransactions, error) {
 	req := NewRequest[StarTransactions]("getStarTransactions", params)
 	return req.Do(api)
 }
 
 // GetStarTransactionsWithContext is the context-aware variant of GetStarTransactions.
+// Since: Bot API 7.5
 // It executes the same request but uses ctx for cancellation and deadlines.
 // See https://core.telegram.org/bots/api#getstartransactions
-func (api *API) GetStarTransactionsWithContext(ctx context.Context, params GetStarTransactionsP) (StarTransactions, error) {
+func (api *API) GetStarTransactionsWithContext(ctx context.Context, params GetStarTransactions) (StarTransactions, error) {
 	req := NewRequest[StarTransactions]("getStarTransactions", params)
 	return req.DoWithContext(ctx, api)
 }
 
-// RefundStarPaymentP holds parameters for the refundStarPayment method.
+// RefundStarPayment holds parameters for the refundStarPayment method.
+// Since: Bot API 7.4
 // See https://core.telegram.org/bots/api#refundstarpayment
-type RefundStarPaymentP struct {
+type RefundStarPayment struct {
 	UserID                  int64  `json:"user_id"`
 	TelegramPaymentChargeID string `json:"telegram_payment_charge_id"`
 }
 
 // RefundStarPayment refunds a successful Telegram Stars payment.
+// Since: Bot API 7.4
 // Returns true on success.
 // See https://core.telegram.org/bots/api#refundstarpayment
-func (api *API) RefundStarPayment(params RefundStarPaymentP) (bool, error) {
+func (api *API) RefundStarPayment(params RefundStarPayment) (bool, error) {
 	req := NewRequest[bool]("refundStarPayment", params)
 	return req.Do(api)
 }
 
 // RefundStarPaymentWithContext is the context-aware variant of RefundStarPayment.
+// Since: Bot API 7.4
 // It executes the same request but uses ctx for cancellation and deadlines.
 // See https://core.telegram.org/bots/api#refundstarpayment
-func (api *API) RefundStarPaymentWithContext(ctx context.Context, params RefundStarPaymentP) (bool, error) {
+func (api *API) RefundStarPaymentWithContext(ctx context.Context, params RefundStarPayment) (bool, error) {
 	req := NewRequest[bool]("refundStarPayment", params)
 	return req.DoWithContext(ctx, api)
 }
 
-// EditUserStarSubscriptionP holds parameters for the editUserStarSubscription method.
+// EditUserStarSubscription holds parameters for the editUserStarSubscription method.
+// Since: Bot API 8.0
 // See https://core.telegram.org/bots/api#edituserstarsubscription
-type EditUserStarSubscriptionP struct {
+type EditUserStarSubscription struct {
 	UserID                  int64  `json:"user_id"`
 	TelegramPaymentChargeID string `json:"telegram_payment_charge_id"`
 	IsCanceled              bool   `json:"is_canceled"`
 }
 
 // EditUserStarSubscription cancels or re-enables a user star subscription extension.
+// Since: Bot API 8.0
 // Returns true on success.
 // See https://core.telegram.org/bots/api#edituserstarsubscription
-func (api *API) EditUserStarSubscription(params EditUserStarSubscriptionP) (bool, error) {
+func (api *API) EditUserStarSubscription(params EditUserStarSubscription) (bool, error) {
 	req := NewRequest[bool]("editUserStarSubscription", params)
 	return req.Do(api)
 }
 
 // EditUserStarSubscriptionWithContext is the context-aware variant of EditUserStarSubscription.
+// Since: Bot API 8.0
 // It executes the same request but uses ctx for cancellation and deadlines.
 // See https://core.telegram.org/bots/api#edituserstarsubscription
-func (api *API) EditUserStarSubscriptionWithContext(ctx context.Context, params EditUserStarSubscriptionP) (bool, error) {
+func (api *API) EditUserStarSubscriptionWithContext(ctx context.Context, params EditUserStarSubscription) (bool, error) {
 	req := NewRequest[bool]("editUserStarSubscription", params)
 	return req.DoWithContext(ctx, api)
 }

tgapi/stars_types.go

@@ -1,6 +1,7 @@
 package tgapi
 
 // StarTransaction describes a Telegram Star transaction.
+// Since: Bot API 7.5
 // See https://core.telegram.org/bots/api#startransaction
 type StarTransaction struct {
 	ID             string         `json:"id"`
@@ -12,6 +13,7 @@ type StarTransaction struct {
 }
 
 // StarTransactions contains a list of Telegram Star transactions.
+// Since: Bot API 7.5
 // See https://core.telegram.org/bots/api#startransactions
 type StarTransactions struct {
 	Transactions []StarTransaction `json:"transactions"`

tgapi/stickers_methods.go

@@ -2,9 +2,10 @@ package tgapi
 
 import "context"
 
-// SendStickerP holds parameters for the sendSticker method.
+// SendSticker holds parameters for the sendSticker method.
+// Since: Bot API 1.3
 // See https://core.telegram.org/bots/api#sendsticker
-type SendStickerP struct {
+type SendSticker struct {
 	BusinessConnectionID  string `json:"business_connection_id,omitempty"`
 	ChatID                int64  `json:"chat_id"`
 	MessageThreadID       int    `json:"message_thread_id,omitempty"`
@@ -23,73 +24,83 @@ type SendStickerP struct {
 }
 
 // SendSticker sends a static .WEBP, animated .TGS, or video .WEBM sticker.
+// Since: Bot API 1.3
 // See https://core.telegram.org/bots/api#sendsticker
-func (api *API) SendSticker(params SendStickerP) (Message, error) {
+func (api *API) SendSticker(params SendSticker) (Message, error) {
 	req := NewRequestWithChatID[Message]("sendSticker", params, params.ChatID)
 	return req.Do(api)
 }
 
 // SendStickerWithContext is the context-aware variant of SendSticker.
+// Since: Bot API 1.3
 // It executes the same request but uses ctx for cancellation and deadlines.
 // See https://core.telegram.org/bots/api#sendsticker
-func (api *API) SendStickerWithContext(ctx context.Context, params SendStickerP) (Message, error) {
+func (api *API) SendStickerWithContext(ctx context.Context, params SendSticker) (Message, error) {
 	req := NewRequestWithChatID[Message]("sendSticker", params, params.ChatID)
 	return req.DoWithContext(ctx, api)
 }
 
-// GetStickerSetP holds parameters for the getStickerSet method.
+// GetStickerSet holds parameters for the getStickerSet method.
+// Since: Bot API 3.2
 // See https://core.telegram.org/bots/api#getstickerset
-type GetStickerSetP struct {
+type GetStickerSet struct {
 	Name string `json:"name"`
 }
 
 // GetStickerSet returns a sticker set by its name.
+// Since: Bot API 3.2
 // See https://core.telegram.org/bots/api#getstickerset
-func (api *API) GetStickerSet(params GetStickerSetP) (StickerSet, error) {
+func (api *API) GetStickerSet(params GetStickerSet) (StickerSet, error) {
 	req := NewRequest[StickerSet]("getStickerSet", params)
 	return req.Do(api)
 }
 
 // GetStickerSetWithContext is the context-aware variant of GetStickerSet.
+// Since: Bot API 3.2
 // It executes the same request but uses ctx for cancellation and deadlines.
 // See https://core.telegram.org/bots/api#getstickerset
-func (api *API) GetStickerSetWithContext(ctx context.Context, params GetStickerSetP) (StickerSet, error) {
+func (api *API) GetStickerSetWithContext(ctx context.Context, params GetStickerSet) (StickerSet, error) {
 	req := NewRequest[StickerSet]("getStickerSet", params)
 	return req.DoWithContext(ctx, api)
 }
 
-// GetCustomEmojiStickersP holds parameters for the getCustomEmojiStickers method.
+// GetCustomEmojiStickers holds parameters for the getCustomEmojiStickers method.
+// Since: Bot API 6.2
 // See https://core.telegram.org/bots/api#getcustomemojistickers
-type GetCustomEmojiStickersP struct {
+type GetCustomEmojiStickers struct {
 	CustomEmojiIDs []string `json:"custom_emoji_ids"`
 }
 
 // GetCustomEmojiStickers returns information about custom emoji stickers by their IDs.
+// Since: Bot API 6.2
 // See https://core.telegram.org/bots/api#getcustomemojistickers
-func (api *API) GetCustomEmojiStickers(params GetCustomEmojiStickersP) ([]Sticker, error) {
+func (api *API) GetCustomEmojiStickers(params GetCustomEmojiStickers) ([]Sticker, error) {
 	req := NewRequest[[]Sticker]("getCustomEmojiStickers", params)
 	return req.Do(api)
 }
 
 // GetCustomEmojiStickersWithContext is the context-aware variant of GetCustomEmojiStickers.
+// Since: Bot API 6.2
 // It executes the same request but uses ctx for cancellation and deadlines.
 // See https://core.telegram.org/bots/api#getcustomemojistickers
-func (api *API) GetCustomEmojiStickersWithContext(ctx context.Context, params GetCustomEmojiStickersP) ([]Sticker, error) {
+func (api *API) GetCustomEmojiStickersWithContext(ctx context.Context, params GetCustomEmojiStickers) ([]Sticker, error) {
 	req := NewRequest[[]Sticker]("getCustomEmojiStickers", params)
 	return req.DoWithContext(ctx, api)
 }
 
-// UploadStickerFileP holds parameters for the uploadStickerFile method.
+// UploadStickerFile holds parameters for the uploadStickerFile method.
+// Since: Bot API 3.2
 // See https://core.telegram.org/bots/api#uploadstickerfile
-type UploadStickerFileP struct {
+type UploadStickerFile struct {
 	UserID        int64              `json:"user_id"`
 	StickerFormat InputStickerFormat `json:"sticker_format"`
 }
 
 // UploadStickerFile uploads a sticker file for later use in sticker set methods.
+// Since: Bot API 3.2
 // sticker is the file to upload.
 // See https://core.telegram.org/bots/api#uploadstickerfile
-func (api *API) UploadStickerFile(params UploadStickerFileP, sticker UploaderFile) (File, error) {
+func (api *API) UploadStickerFile(params UploadStickerFile, sticker UploaderFile) (File, error) {
 	uploader := NewUploader(api)
 	defer func() {
 		_ = uploader.Close()
@@ -99,9 +110,10 @@ func (api *API) UploadStickerFile(params UploadStickerFileP, sticker UploaderFil
 }
 
 // UploadStickerFileWithContext is the context-aware variant of UploadStickerFile.
+// Since: Bot API 3.2
 // It executes the same request but uses ctx for cancellation and deadlines.
 // See https://core.telegram.org/bots/api#uploadstickerfile
-func (api *API) UploadStickerFileWithContext(ctx context.Context, params UploadStickerFileP, sticker UploaderFile) (File, error) {
+func (api *API) UploadStickerFileWithContext(ctx context.Context, params UploadStickerFile, sticker UploaderFile) (File, error) {
 	uploader := NewUploader(api)
 	defer func() {
 		_ = uploader.Close()
@@ -110,9 +122,10 @@ func (api *API) UploadStickerFileWithContext(ctx context.Context, params UploadS
 	return req.DoWithContext(ctx, uploader)
 }
 
-// CreateNewStickerSetP holds parameters for the createNewStickerSet method.
+// CreateNewStickerSet holds parameters for the createNewStickerSet method.
+// Since: Bot API 3.2
 // See https://core.telegram.org/bots/api#createnewstickerset
-type CreateNewStickerSetP struct {
+type CreateNewStickerSet struct {
 	UserID int64  `json:"user_id"`
 	Name   string `json:"name"`
 	Title  string `json:"title"`
@@ -123,93 +136,105 @@ type CreateNewStickerSetP struct {
 }
 
 // CreateNewStickerSet creates a new sticker set owned by a user.
+// Since: Bot API 3.2
 // Returns True on success.
 // See https://core.telegram.org/bots/api#createnewstickerset
-func (api *API) CreateNewStickerSet(params CreateNewStickerSetP) (bool, error) {
+func (api *API) CreateNewStickerSet(params CreateNewStickerSet) (bool, error) {
 	req := NewRequest[bool]("createNewStickerSet", params)
 	return req.Do(api)
 }
 
 // CreateNewStickerSetWithContext is the context-aware variant of CreateNewStickerSet.
+// Since: Bot API 3.2
 // It executes the same request but uses ctx for cancellation and deadlines.
 // See https://core.telegram.org/bots/api#createnewstickerset
-func (api *API) CreateNewStickerSetWithContext(ctx context.Context, params CreateNewStickerSetP) (bool, error) {
+func (api *API) CreateNewStickerSetWithContext(ctx context.Context, params CreateNewStickerSet) (bool, error) {
 	req := NewRequest[bool]("createNewStickerSet", params)
 	return req.DoWithContext(ctx, api)
 }
 
-// AddStickerToSetP holds parameters for the addStickerToSet method.
+// AddStickerToSet holds parameters for the addStickerToSet method.
+// Since: Bot API 3.2
 // See https://core.telegram.org/bots/api#addstickertoset
-type AddStickerToSetP struct {
+type AddStickerToSet struct {
 	UserID  int64        `json:"user_id"`
 	Name    string       `json:"name"`
 	Sticker InputSticker `json:"sticker"`
 }
 
 // AddStickerToSet adds a new sticker to a set created by the bot.
+// Since: Bot API 3.2
 // Returns True on success.
 // See https://core.telegram.org/bots/api#addstickertoset
-func (api *API) AddStickerToSet(params AddStickerToSetP) (bool, error) {
+func (api *API) AddStickerToSet(params AddStickerToSet) (bool, error) {
 	req := NewRequest[bool]("addStickerToSet", params)
 	return req.Do(api)
 }
 
 // AddStickerToSetWithContext is the context-aware variant of AddStickerToSet.
+// Since: Bot API 3.2
 // It executes the same request but uses ctx for cancellation and deadlines.
 // See https://core.telegram.org/bots/api#addstickertoset
-func (api *API) AddStickerToSetWithContext(ctx context.Context, params AddStickerToSetP) (bool, error) {
+func (api *API) AddStickerToSetWithContext(ctx context.Context, params AddStickerToSet) (bool, error) {
 	req := NewRequest[bool]("addStickerToSet", params)
 	return req.DoWithContext(ctx, api)
 }
 
-// SetStickerPositionInSetP holds parameters for the setStickerPositionInSet method.
+// SetStickerPositionInSet holds parameters for the setStickerPositionInSet method.
+// Since: Bot API 3.2
 // See https://core.telegram.org/bots/api#setstickerpositioninset
-type SetStickerPositionInSetP struct {
+type SetStickerPositionInSet struct {
 	Sticker  string `json:"sticker"`
 	Position int    `json:"position"`
 }
 
 // SetStickerPositionInSet moves a sticker in a set to a specific position.
+// Since: Bot API 3.2
 // Returns True on success.
 // See https://core.telegram.org/bots/api#setstickerpositioninset
-func (api *API) SetStickerPositionInSet(params SetStickerPositionInSetP) (bool, error) {
+func (api *API) SetStickerPositionInSet(params SetStickerPositionInSet) (bool, error) {
 	req := NewRequest[bool]("setStickerPositionInSet", params)
 	return req.Do(api)
 }
 
 // SetStickerPositionInSetWithContext is the context-aware variant of SetStickerPositionInSet.
+// Since: Bot API 3.2
 // It executes the same request but uses ctx for cancellation and deadlines.
 // See https://core.telegram.org/bots/api#setstickerpositioninset
-func (api *API) SetStickerPositionInSetWithContext(ctx context.Context, params SetStickerPositionInSetP) (bool, error) {
+func (api *API) SetStickerPositionInSetWithContext(ctx context.Context, params SetStickerPositionInSet) (bool, error) {
 	req := NewRequest[bool]("setStickerPositionInSet", params)
 	return req.DoWithContext(ctx, api)
 }
 
-// DeleteStickerFromSetP holds parameters for the deleteStickerFromSet method.
+// DeleteStickerFromSet holds parameters for the deleteStickerFromSet method.
+// Since: Bot API 3.2
 // See https://core.telegram.org/bots/api#deletestickerfromset
-type DeleteStickerFromSetP struct {
+type DeleteStickerFromSet struct {
 	Sticker string `json:"sticker"`
 }
 
 // DeleteStickerFromSet deletes a sticker from a set created by the bot.
+// Since: Bot API 3.2
 // Returns True on success.
 // See https://core.telegram.org/bots/api#deletestickerfromset
-func (api *API) DeleteStickerFromSet(params DeleteStickerFromSetP) (bool, error) {
+func (api *API) DeleteStickerFromSet(params DeleteStickerFromSet) (bool, error) {
 	req := NewRequest[bool]("deleteStickerFromSet", params)
 	return req.Do(api)
 }
 
 // DeleteStickerFromSetWithContext is the context-aware variant of DeleteStickerFromSet.
+// Since: Bot API 3.2
 // It executes the same request but uses ctx for cancellation and deadlines.
 // See https://core.telegram.org/bots/api#deletestickerfromset
-func (api *API) DeleteStickerFromSetWithContext(ctx context.Context, params DeleteStickerFromSetP) (bool, error) {
+func (api *API) DeleteStickerFromSetWithContext(ctx context.Context, params DeleteStickerFromSet) (bool, error) {
 	req := NewRequest[bool]("deleteStickerFromSet", params)
 	return req.DoWithContext(ctx, api)
 }
 
-// ReplaceStickerInSetP holds parameters for the replaceStickerInSet method.
+// ReplaceStickerInSet holds parameters for the replaceStickerInSet method.
+// Since: Bot API 7.2
 // See https://core.telegram.org/bots/api#replacestickerinset
-type ReplaceStickerInSetP struct {
+type ReplaceStickerInSet struct {
 	UserID     int64        `json:"user_id"`
 	Name       string       `json:"name"`
 	OldSticker string       `json:"old_sticker"`
@@ -217,116 +242,131 @@ type ReplaceStickerInSetP struct {
 }
 
 // ReplaceStickerInSet replaces an existing sticker in a set with a new one.
+// Since: Bot API 7.2
 // Returns True on success.
 // See https://core.telegram.org/bots/api#replacestickerinset
-func (api *API) ReplaceStickerInSet(params ReplaceStickerInSetP) (bool, error) {
+func (api *API) ReplaceStickerInSet(params ReplaceStickerInSet) (bool, error) {
 	req := NewRequest[bool]("replaceStickerInSet", params)
 	return req.Do(api)
 }
 
 // ReplaceStickerInSetWithContext is the context-aware variant of ReplaceStickerInSet.
+// Since: Bot API 7.2
 // It executes the same request but uses ctx for cancellation and deadlines.
 // See https://core.telegram.org/bots/api#replacestickerinset
-func (api *API) ReplaceStickerInSetWithContext(ctx context.Context, params ReplaceStickerInSetP) (bool, error) {
+func (api *API) ReplaceStickerInSetWithContext(ctx context.Context, params ReplaceStickerInSet) (bool, error) {
 	req := NewRequest[bool]("replaceStickerInSet", params)
 	return req.DoWithContext(ctx, api)
 }
 
-// SetStickerEmojiListP holds parameters for the setStickerEmojiList method.
+// SetStickerEmojiList holds parameters for the setStickerEmojiList method.
+// Since: Bot API 6.6
 // See https://core.telegram.org/bots/api#setstickeremojilist
-type SetStickerEmojiListP struct {
+type SetStickerEmojiList struct {
 	Sticker   string   `json:"sticker"`
 	EmojiList []string `json:"emoji_list"`
 }
 
 // SetStickerEmojiList changes the list of emoji associated with a sticker.
+// Since: Bot API 6.6
 // Returns True on success.
 // See https://core.telegram.org/bots/api#setstickeremojilist
-func (api *API) SetStickerEmojiList(params SetStickerEmojiListP) (bool, error) {
+func (api *API) SetStickerEmojiList(params SetStickerEmojiList) (bool, error) {
 	req := NewRequest[bool]("setStickerEmojiList", params)
 	return req.Do(api)
 }
 
 // SetStickerEmojiListWithContext is the context-aware variant of SetStickerEmojiList.
+// Since: Bot API 6.6
 // It executes the same request but uses ctx for cancellation and deadlines.
 // See https://core.telegram.org/bots/api#setstickeremojilist
-func (api *API) SetStickerEmojiListWithContext(ctx context.Context, params SetStickerEmojiListP) (bool, error) {
+func (api *API) SetStickerEmojiListWithContext(ctx context.Context, params SetStickerEmojiList) (bool, error) {
 	req := NewRequest[bool]("setStickerEmojiList", params)
 	return req.DoWithContext(ctx, api)
 }
 
-// SetStickerKeywordsP holds parameters for the setStickerKeywords method.
+// SetStickerKeywords holds parameters for the setStickerKeywords method.
+// Since: Bot API 6.6
 // See https://core.telegram.org/bots/api#setstickerkeywords
-type SetStickerKeywordsP struct {
+type SetStickerKeywords struct {
 	Sticker  string   `json:"sticker"`
 	Keywords []string `json:"keywords"`
 }
 
 // SetStickerKeywords changes the keywords of a sticker.
+// Since: Bot API 6.6
 // Returns True on success.
 // See https://core.telegram.org/bots/api#setstickerkeywords
-func (api *API) SetStickerKeywords(params SetStickerKeywordsP) (bool, error) {
+func (api *API) SetStickerKeywords(params SetStickerKeywords) (bool, error) {
 	req := NewRequest[bool]("setStickerKeywords", params)
 	return req.Do(api)
 }
 
 // SetStickerKeywordsWithContext is the context-aware variant of SetStickerKeywords.
+// Since: Bot API 6.6
 // It executes the same request but uses ctx for cancellation and deadlines.
 // See https://core.telegram.org/bots/api#setstickerkeywords
-func (api *API) SetStickerKeywordsWithContext(ctx context.Context, params SetStickerKeywordsP) (bool, error) {
+func (api *API) SetStickerKeywordsWithContext(ctx context.Context, params SetStickerKeywords) (bool, error) {
 	req := NewRequest[bool]("setStickerKeywords", params)
 	return req.DoWithContext(ctx, api)
 }
 
-// SetStickerMaskPositionP holds parameters for the setStickerMaskPosition method.
+// SetStickerMaskPosition holds parameters for the setStickerMaskPosition method.
+// Since: Bot API 6.6
 // See https://core.telegram.org/bots/api#setstickermaskposition
-type SetStickerMaskPositionP struct {
+type SetStickerMaskPosition struct {
 	Sticker      string        `json:"sticker"`
 	MaskPosition *MaskPosition `json:"mask_position,omitempty"`
 }
 
 // SetStickerMaskPosition changes the mask position of a mask sticker.
+// Since: Bot API 6.6
 // Returns True on success.
 // See https://core.telegram.org/bots/api#setstickermaskposition
-func (api *API) SetStickerMaskPosition(params SetStickerMaskPositionP) (bool, error) {
+func (api *API) SetStickerMaskPosition(params SetStickerMaskPosition) (bool, error) {
 	req := NewRequest[bool]("setStickerMaskPosition", params)
 	return req.Do(api)
 }
 
 // SetStickerMaskPositionWithContext is the context-aware variant of SetStickerMaskPosition.
+// Since: Bot API 6.6
 // It executes the same request but uses ctx for cancellation and deadlines.
 // See https://core.telegram.org/bots/api#setstickermaskposition
-func (api *API) SetStickerMaskPositionWithContext(ctx context.Context, params SetStickerMaskPositionP) (bool, error) {
+func (api *API) SetStickerMaskPositionWithContext(ctx context.Context, params SetStickerMaskPosition) (bool, error) {
 	req := NewRequest[bool]("setStickerMaskPosition", params)
 	return req.DoWithContext(ctx, api)
 }
 
-// SetStickerSetTitleP holds parameters for the setStickerSetTitle method.
+// SetStickerSetTitle holds parameters for the setStickerSetTitle method.
+// Since: Bot API 6.6
 // See https://core.telegram.org/bots/api#setstickersettitle
-type SetStickerSetTitleP struct {
+type SetStickerSetTitle struct {
 	Name  string `json:"name"`
 	Title string `json:"title"`
 }
 
 // SetStickerSetTitle sets the title of a sticker set created by the bot.
+// Since: Bot API 6.6
 // Returns True on success.
 // See https://core.telegram.org/bots/api#setstickersettitle
-func (api *API) SetStickerSetTitle(params SetStickerSetTitleP) (bool, error) {
+func (api *API) SetStickerSetTitle(params SetStickerSetTitle) (bool, error) {
 	req := NewRequest[bool]("setStickerSetTitle", params)
 	return req.Do(api)
 }
 
 // SetStickerSetTitleWithContext is the context-aware variant of SetStickerSetTitle.
+// Since: Bot API 6.6
 // It executes the same request but uses ctx for cancellation and deadlines.
 // See https://core.telegram.org/bots/api#setstickersettitle
-func (api *API) SetStickerSetTitleWithContext(ctx context.Context, params SetStickerSetTitleP) (bool, error) {
+func (api *API) SetStickerSetTitleWithContext(ctx context.Context, params SetStickerSetTitle) (bool, error) {
 	req := NewRequest[bool]("setStickerSetTitle", params)
 	return req.DoWithContext(ctx, api)
 }
 
-// SetStickerSetThumbnailP holds parameters for the setStickerSetThumbnail method.
+// SetStickerSetThumbnail holds parameters for the setStickerSetThumbnail method.
+// Since: Bot API 6.6
 // See https://core.telegram.org/bots/api#setstickersetthumbnail
-type SetStickerSetThumbnailP struct {
+type SetStickerSetThumbnail struct {
 	Name      string             `json:"name"`
 	UserID    int64              `json:"user_id"`
 	Thumbnail string             `json:"thumbnail"`
@@ -334,62 +374,70 @@ type SetStickerSetThumbnailP struct {
 }
 
 // SetStickerSetThumbnail sets the thumbnail of a sticker set.
+// Since: Bot API 6.6
 // Returns True on success.
 // See https://core.telegram.org/bots/api#setstickersetthumbnail
-func (api *API) SetStickerSetThumbnail(params SetStickerSetThumbnailP) (bool, error) {
+func (api *API) SetStickerSetThumbnail(params SetStickerSetThumbnail) (bool, error) {
 	req := NewRequest[bool]("setStickerSetThumbnail", params)
 	return req.Do(api)
 }
 
 // SetStickerSetThumbnailWithContext is the context-aware variant of SetStickerSetThumbnail.
+// Since: Bot API 6.6
 // It executes the same request but uses ctx for cancellation and deadlines.
 // See https://core.telegram.org/bots/api#setstickersetthumbnail
-func (api *API) SetStickerSetThumbnailWithContext(ctx context.Context, params SetStickerSetThumbnailP) (bool, error) {
+func (api *API) SetStickerSetThumbnailWithContext(ctx context.Context, params SetStickerSetThumbnail) (bool, error) {
 	req := NewRequest[bool]("setStickerSetThumbnail", params)
 	return req.DoWithContext(ctx, api)
 }
 
-// SetCustomEmojiStickerSetThumbnailP holds parameters for the setCustomEmojiStickerSetThumbnail method.
+// SetCustomEmojiStickerSetThumbnail holds parameters for the setCustomEmojiStickerSetThumbnail method.
+// Since: Bot API 6.6
 // See https://core.telegram.org/bots/api#setcustomemojistickersetthumbnail
-type SetCustomEmojiStickerSetThumbnailP struct {
+type SetCustomEmojiStickerSetThumbnail struct {
 	Name          string `json:"name"`
 	CustomEmojiID string `json:"custom_emoji_id,omitempty"`
 }
 
 // SetCustomEmojiStickerSetThumbnail sets the thumbnail of a custom emoji sticker set.
+// Since: Bot API 6.6
 // Returns True on success.
 // See https://core.telegram.org/bots/api#setcustomemojistickersetthumbnail
-func (api *API) SetCustomEmojiStickerSetThumbnail(params SetCustomEmojiStickerSetThumbnailP) (bool, error) {
+func (api *API) SetCustomEmojiStickerSetThumbnail(params SetCustomEmojiStickerSetThumbnail) (bool, error) {
 	req := NewRequest[bool]("setCustomEmojiStickerSetThumbnail", params)
 	return req.Do(api)
 }
 
 // SetCustomEmojiStickerSetThumbnailWithContext is the context-aware variant of SetCustomEmojiStickerSetThumbnail.
+// Since: Bot API 6.6
 // It executes the same request but uses ctx for cancellation and deadlines.
 // See https://core.telegram.org/bots/api#setcustomemojistickersetthumbnail
-func (api *API) SetCustomEmojiStickerSetThumbnailWithContext(ctx context.Context, params SetCustomEmojiStickerSetThumbnailP) (bool, error) {
+func (api *API) SetCustomEmojiStickerSetThumbnailWithContext(ctx context.Context, params SetCustomEmojiStickerSetThumbnail) (bool, error) {
 	req := NewRequest[bool]("setCustomEmojiStickerSetThumbnail", params)
 	return req.DoWithContext(ctx, api)
 }
 
-// DeleteStickerSetP holds parameters for the deleteStickerSet method.
+// DeleteStickerSet holds parameters for the deleteStickerSet method.
+// Since: Bot API 6.6
 // See https://core.telegram.org/bots/api#deletestickerset
-type DeleteStickerSetP struct {
+type DeleteStickerSet struct {
 	Name string `json:"name"`
 }
 
 // DeleteStickerSet deletes a sticker set created by the bot.
+// Since: Bot API 6.6
 // Returns True on success.
 // See https://core.telegram.org/bots/api#deletestickerset
-func (api *API) DeleteStickerSet(params DeleteStickerSetP) (bool, error) {
+func (api *API) DeleteStickerSet(params DeleteStickerSet) (bool, error) {
 	req := NewRequest[bool]("deleteStickerSet", params)
 	return req.Do(api)
 }
 
 // DeleteStickerSetWithContext is the context-aware variant of DeleteStickerSet.
+// Since: Bot API 6.6
 // It executes the same request but uses ctx for cancellation and deadlines.
 // See https://core.telegram.org/bots/api#deletestickerset
-func (api *API) DeleteStickerSetWithContext(ctx context.Context, params DeleteStickerSetP) (bool, error) {
+func (api *API) DeleteStickerSetWithContext(ctx context.Context, params DeleteStickerSet) (bool, error) {
 	req := NewRequest[bool]("deleteStickerSet", params)
 	return req.DoWithContext(ctx, api)
 }

tgapi/stickers_types.go

@@ -15,6 +15,7 @@ const (
 )
 
 // MaskPosition describes the position on faces where a mask should be placed by default.
+// Since: Bot API 3.2
 // See https://core.telegram.org/bots/api#maskposition
 type MaskPosition struct {
 	Point  MaskPositionPoint `json:"point"`
@@ -36,26 +37,28 @@ const (
 )
 
 // Sticker represents a sticker.
+// Since: Bot API 1.0
 // See https://core.telegram.org/bots/api#sticker
 type Sticker struct {
-	FileId       string      `json:"file_id"`
+	FileID       string `json:"file_id"`
-	FileUniqueId string      `json:"file_unique_id"`
+	FileUniqueID string `json:"file_unique_id"`
-	Type         StickerType `json:"type"`
+	Width        int    `json:"width"`
-	Width        int         `json:"width"`
+	Height       int    `json:"height"`
-	Height       int         `json:"height"`
-	IsAnimated   bool        `json:"is_animated"`
-	IsVideo      bool        `json:"is_video"`
 
-	Thumbnail      *PhotoSize    `json:"thumbnail,omitempty"`
+	Type           StickerType   `json:"type"`                // Since: Bot API 6.2
+	IsAnimated     bool          `json:"is_animated"`         // Since: Bot API 4.4
+	IsVideo        bool          `json:"is_video"`            // Since: Bot API 5.7
+	Thumbnail      *PhotoSize    `json:"thumbnail,omitempty"` // Since: Bot API 6.6
 	Emoji          *string       `json:"emoji,omitempty"`
-	SetName        *string       `json:"set_name,omitempty"`
+	SetName        *string       `json:"set_name,omitempty"`        // Since: Bot API 3.2
-	MaskPosition   *MaskPosition `json:"mask_position,omitempty"`
+	MaskPosition   *MaskPosition `json:"mask_position,omitempty"`   // Since: Bot API 3.2
-	CustomEmojiID  *string       `json:"custom_emoji_id,omitempty"`
+	CustomEmojiID  *string       `json:"custom_emoji_id,omitempty"` // Since: Bot API 6.2
-	NeedRepainting *bool         `json:"need_repainting,omitempty"`
+	NeedRepainting *bool         `json:"need_repainting,omitempty"` // Since: Bot API 6.6
 	FileSize       *int64        `json:"file_size,omitempty"`
 }
 
 // StickerSet represents a sticker set.
+// Since: Bot API 3.2
 // See https://core.telegram.org/bots/api#stickerset
 type StickerSet struct {
 	Name        string      `json:"name"`
@@ -78,6 +81,7 @@ const (
 )
 
 // InputSticker describes a sticker to be added to a sticker set.
+// Since: Bot API 6.6
 // See https://core.telegram.org/bots/api#inputsticker
 type InputSticker struct {
 	Sticker      string             `json:"sticker"`

tgapi/types.go

@@ -57,9 +57,16 @@ const (
 	UpdateTypeChatBoost UpdateType = "chat_boost"
 	// UpdateTypeRemovedChatBoost is a removed chat boost update.
 	UpdateTypeRemovedChatBoost UpdateType = "removed_chat_boost"
+
+	// UpdateTypeManagedBot is a managed bot update.
+	UpdateTypeManagedBot UpdateType = "managed_bot"
+
+	// UpdateTypeGuestMessage is a guest message update.
+	UpdateTypeGuestMessage UpdateType = "guest_message"
 )
 
 // Update represents an incoming update from Telegram.
+// Since: Bot API 1.0
 // See https://core.telegram.org/bots/api#update
 type Update struct {
 	Type UpdateType `json:"-"`
@@ -67,30 +74,33 @@ type Update struct {
 	UpdateID          int      `json:"update_id"`
 	Message           *Message `json:"message,omitempty"`
 	EditedMessage     *Message `json:"edited_message,omitempty"`
-	ChannelPost       *Message `json:"channel_post,omitempty"`
+	ChannelPost       *Message `json:"channel_post,omitempty"`        // Since: Bot API 2.3
-	EditedChannelPost *Message `json:"edited_channel_post,omitempty"`
+	EditedChannelPost *Message `json:"edited_channel_post,omitempty"` // Since: Bot API 2.3
 
-	BusinessConnection      *BusinessConnection          `json:"business_connection,omitempty"`
+	BusinessConnection      *BusinessConnection          `json:"business_connection,omitempty"`       // Since: Bot API 7.2
-	BusinessMessage         *Message                     `json:"business_message,omitempty"`
+	BusinessMessage         *Message                     `json:"business_message,omitempty"`          // Since: Bot API 7.2
-	EditedBusinessMessage   *Message                     `json:"edited_business_message,omitempty"`
+	EditedBusinessMessage   *Message                     `json:"edited_business_message,omitempty"`   // Since: Bot API 7.2
-	DeletedBusinessMessages *BusinessMessagesDeleted     `json:"deleted_business_messages,omitempty"`
+	DeletedBusinessMessages *BusinessMessagesDeleted     `json:"deleted_business_messages,omitempty"` // Since: Bot API 7.2
-	MessageReaction         *MessageReactionUpdated      `json:"message_reaction,omitempty"`
+	GuestMessage            *Message                     `json:"guest_message,omitempty"`             // Since: Bot API 10.0
-	MessageReactionCount    *MessageReactionCountUpdated `json:"message_reaction_count,omitempty"`
+	MessageReaction         *MessageReactionUpdated      `json:"message_reaction,omitempty"`          // Since: Bot API 7.0
+	MessageReactionCount    *MessageReactionCountUpdated `json:"message_reaction_count,omitempty"`    // Since: Bot API 7.0
 
-	InlineQuery        *InlineQuery        `json:"inline_query,omitempty"`
+	InlineQuery        *InlineQuery        `json:"inline_query,omitempty"`         // Since: Bot API 1.7
-	ChosenInlineResult *ChosenInlineResult `json:"chosen_inline_result,omitempty"`
+	ChosenInlineResult *ChosenInlineResult `json:"chosen_inline_result,omitempty"` // Since: Bot API 1.8
-	CallbackQuery      *CallbackQuery      `json:"callback_query,omitempty"`
+	CallbackQuery      *CallbackQuery      `json:"callback_query,omitempty"`       // Since: Bot API 2.0
-	ShippingQuery      *ShippingQuery      `json:"shipping_query,omitempty"`
+	ShippingQuery      *ShippingQuery      `json:"shipping_query,omitempty"`       // Since: Bot API 3.0
-	PreCheckoutQuery   *PreCheckoutQuery   `json:"pre_checkout_query,omitempty"`
+	PreCheckoutQuery   *PreCheckoutQuery   `json:"pre_checkout_query,omitempty"`   // Since: Bot API 3.0
-	PurchasedPaidMedia *PaidMediaPurchased `json:"purchased_paid_media,omitempty"`
+	PurchasedPaidMedia *PaidMediaPurchased `json:"purchased_paid_media,omitempty"` // Since: Bot API 7.10
 
-	Poll             *Poll              `json:"poll,omitempty"`
+	Poll             *Poll              `json:"poll,omitempty"`               // Since: Bot API 4.2
-	PollAnswer       *PollAnswer        `json:"poll_answer,omitempty"`
+	PollAnswer       *PollAnswer        `json:"poll_answer,omitempty"`        // Since: Bot API 4.6
-	MyChatMember     *ChatMemberUpdated `json:"my_chat_member,omitempty"`
+	MyChatMember     *ChatMemberUpdated `json:"my_chat_member,omitempty"`     // Since: Bot API 5.1
-	ChatMember       *ChatMemberUpdated `json:"chat_member,omitempty"`
+	ChatMember       *ChatMemberUpdated `json:"chat_member,omitempty"`        // Since: Bot API 5.1
-	ChatJoinRequest  *ChatJoinRequest   `json:"chat_join_request,omitempty"`
+	ChatJoinRequest  *ChatJoinRequest   `json:"chat_join_request,omitempty"`  // Since: Bot API 5.4
-	ChatBoost        *ChatBoostUpdated  `json:"chat_boost,omitempty"`
+	ChatBoost        *ChatBoostUpdated  `json:"chat_boost,omitempty"`         // Since: Bot API 7.0
-	RemovedChatBoost *ChatBoostRemoved  `json:"removed_chat_boost,omitempty"`
+	RemovedChatBoost *ChatBoostRemoved  `json:"removed_chat_boost,omitempty"` // Since: Bot API 7.0
+
+	ManagedBot *ManagedBotUpdated `json:"managed_bot,omitempty"` // Since: Bot API 9.6
 }
 
 // UnmarshalJSON decodes an update and derives its Type from the populated payload field.
@@ -122,6 +132,8 @@ func (u *Update) UnmarshalJSON(data []byte) error {
 		u.Type = UpdateTypeEditedBusinessMessage
 	case u.DeletedBusinessMessages != nil:
 		u.Type = UpdateTypeDeletedBusinessMessages
+	case u.GuestMessage != nil:
+		u.Type = UpdateTypeGuestMessage
 	case u.MessageReaction != nil:
 		u.Type = UpdateTypeMessageReaction
 	case u.MessageReactionCount != nil:
@@ -154,6 +166,8 @@ func (u *Update) UnmarshalJSON(data []byte) error {
 		u.Type = UpdateTypeChatBoost
 	case u.RemovedChatBoost != nil:
 		u.Type = UpdateTypeRemovedChatBoost
+	case u.ManagedBot != nil:
+		u.Type = UpdateTypeManagedBot
 	default:
 		u.Type = UpdateTypeUnknown
 	}
@@ -161,7 +175,31 @@ func (u *Update) UnmarshalJSON(data []byte) error {
 	return nil
 }
 
+// WebhookInfo describes the current webhook status.
+// Since: Bot API 2.2
+// See https://core.telegram.org/bots/api#webhookinfo
+type WebhookInfo struct {
+	URL                          string   `json:"url"`
+	HasCustomCertificate         bool     `json:"has_custom_certificate"`
+	PendingUpdateCount           int      `json:"pending_update_count"`
+	IPAddress                    string   `json:"ip_address,omitempty"`
+	LastErrorDate                int      `json:"last_error_date,omitempty"`
+	LastErrorMessage             string   `json:"last_error_message,omitempty"`
+	LastSynchronizationErrorDate int      `json:"last_synchronization_error_date,omitempty"`
+	MaxConnections               int      `json:"max_connections,omitempty"`
+	AllowedUpdates               []string `json:"allowed_updates,omitempty"`
+}
+
+// ProximityAlertTriggered represents the content of a service message sent when a user triggers a proximity alert.
+// Since: Bot API 5.0
+type ProximityAlertTriggered struct {
+	Traveler User `json:"traveler"`
+	Watcher  User `json:"watcher"`
+	Distance int  `json:"distance"`
+}
+
 // InlineQuery represents an incoming inline query.
+// Since: Bot API 1.7
 // See https://core.telegram.org/bots/api#inlinequery
 type InlineQuery struct {
 	ID       string    `json:"id"`
@@ -173,6 +211,7 @@ type InlineQuery struct {
 }
 
 // ChosenInlineResult represents a result of an inline query that was chosen by the user.
+// Since: Bot API 1.8
 // See https://core.telegram.org/bots/api#choseninlineresult
 type ChosenInlineResult struct {
 	ResultID        string    `json:"result_id"`
@@ -182,116 +221,18 @@ type ChosenInlineResult struct {
 	Query           string    `json:"query"`
 }
 
-// ShippingQuery represents an incoming shipping query.
-// See https://core.telegram.org/bots/api#shippingquery
-type ShippingQuery struct {
-	ID              string          `json:"id"`
-	From            User            `json:"from"`
-	InvoicePayload  string          `json:"invoice_payload"`
-	ShippingAddress ShippingAddress `json:"shipping_address"`
-}
-
-// ShippingAddress represents a shipping address.
-// See https://core.telegram.org/bots/api#shippingaddress
-type ShippingAddress struct {
-	CountryCode string `json:"country_code"`
-	State       string `json:"state"`
-	City        string `json:"city"`
-	StreetLine1 string `json:"street_line1"`
-	StreetLine2 string `json:"street_line2"`
-	PostCode    string `json:"post_code"`
-}
-
-// OrderInfo represents information about an order.
-// See https://core.telegram.org/bots/api#orderinfo
-type OrderInfo struct {
-	Name            string          `json:"name"`
-	PhoneNumber     string          `json:"phone_number"`
-	Email           string          `json:"email"`
-	ShippingAddress ShippingAddress `json:"shipping_address"`
-}
-
-// PreCheckoutQuery represents an incoming pre-checkout query.
-// See https://core.telegram.org/bots/api#precheckoutquery
-type PreCheckoutQuery struct {
-	ID               string     `json:"id"`
-	From             User       `json:"from"`
-	Currency         string     `json:"currency"`
-	TotalAmount      int        `json:"total_amount"`
-	InvoicePayload   string     `json:"invoice_payload"`
-	ShippingOptionID string     `json:"shipping_option_id"`
-	OrderInfo        *OrderInfo `json:"order_info,omitempty"`
-}
-
-// PaidMediaPurchased represents a purchased paid media.
-// See https://core.telegram.org/bots/api#paidmediapurchased
-type PaidMediaPurchased struct {
-	From             User   `json:"from"`
-	PaidMediaPayload string `json:"paid_media_payload"`
-}
-
 // File represents a file ready to be downloaded.
+// Since: Bot API 1.0
 // See https://core.telegram.org/bots/api#file
 type File struct {
-	FileId       string `json:"file_id"`
+	FileID       string `json:"file_id"`
 	FileUniqueID string `json:"file_unique_id"`
 	FileSize     int64  `json:"file_size,omitempty"`
 	FilePath     string `json:"file_path,omitempty"`
 }
 
-// Audio represents an audio file to be treated as music by the Telegram clients.
-// See https://core.telegram.org/bots/api#audio
-type Audio struct {
-	FileID       string `json:"file_id"`
-	FileUniqueID string `json:"file_unique_id"`
-	Duration     int    `json:"duration"`
-
-	Performer string     `json:"performer,omitempty"`
-	Title     string     `json:"title,omitempty"`
-	FileName  string     `json:"file_name,omitempty"`
-	MimeType  string     `json:"mime_type,omitempty"`
-	FileSize  int64      `json:"file_size,omitempty"`
-	Thumbnail *PhotoSize `json:"thumbnail,omitempty"`
-}
-
-// PollOption contains information about one answer option in a poll.
-// See https://core.telegram.org/bots/api#polloption
-type PollOption struct {
-	Text         string          `json:"text"`
-	TextEntities []MessageEntity `json:"text_entities"`
-	VoterCount   int             `json:"voter_count"`
-}
-
-// Poll contains information about a poll.
-// See https://core.telegram.org/bots/api#poll
-type Poll struct {
-	ID               string          `json:"id"`
-	Question         string          `json:"question"`
-	QuestionEntities []MessageEntity `json:"question_entities"`
-	Options          []PollOption    `json:"options"`
-	TotalVoterCount  int             `json:"total_voter_count"`
-	IsClosed         bool            `json:"is_closed"`
-	IsAnonymous      bool            `json:"is_anonymous"`
-	Type             PollType        `json:"type"`
-
-	AllowsMultipleAnswers bool            `json:"allows_multiple_answers"`
-	CorrectOptionID       *int            `json:"correct_option_id,omitempty"`
-	Explanation           *string         `json:"explanation,omitempty"`
-	ExplanationEntities   []MessageEntity `json:"explanation_entities,omitempty"`
-	OpenPeriod            int             `json:"open_period,omitempty"`
-	CloseDate             int             `json:"close_date,omitempty"`
-}
-
-// PollAnswer represents an answer of a user in a poll.
-// See https://core.telegram.org/bots/api#pollanswer
-type PollAnswer struct {
-	PollID    string `json:"poll_id"`
-	VoterChat Chat   `json:"voter_chat"`
-	User      User   `json:"user"`
-	OptionIDS []int  `json:"option_ids"`
-}
-
 // ChatMemberUpdated represents changes in the status of a chat member.
+// Since: Bot API 5.1
 // See https://core.telegram.org/bots/api#chatmemberupdated
 type ChatMemberUpdated struct {
 	Chat                    Chat            `json:"chat"`
@@ -305,6 +246,7 @@ type ChatMemberUpdated struct {
 }
 
 // ChatJoinRequest represents a join request sent to a chat.
+// Since: Bot API 5.4
 // See https://core.telegram.org/bots/api#chatjoinrequest
 type ChatJoinRequest struct {
 	Chat       Chat            `json:"chat"`
@@ -316,6 +258,7 @@ type ChatJoinRequest struct {
 }
 
 // Location represents a point on the map.
+// Since: Bot API 1.0
 // See https://core.telegram.org/bots/api#location
 type Location struct {
 	Latitude             float64 `json:"latitude"`
@@ -327,6 +270,7 @@ type Location struct {
 }
 
 // LocationAddress represents a human-readable address of a location.
+// Since: Bot API 8.0
 type LocationAddress struct {
 	CountryCode string  `json:"country_code"`
 	State       *string `json:"state,omitempty"`
@@ -335,6 +279,7 @@ type LocationAddress struct {
 }
 
 // Venue represents a venue.
+// Since: Bot API 2.0
 // See https://core.telegram.org/bots/api#venue
 type Venue struct {
 	Location        Location `json:"location"`
@@ -347,24 +292,28 @@ type Venue struct {
 }
 
 // WebAppInfo contains information about a Web App.
+// Since: Bot API 6.0
 // See https://core.telegram.org/bots/api#webappinfo
 type WebAppInfo struct {
 	URL string `json:"url"`
 }
 
+// WebAppData represents data sent from a Web App to the bot.
+// Since: Bot API 6.0
+type WebAppData struct {
+	Data       string `json:"data"`
+	ButtonText string `json:"button_text"`
+}
+
 // StarAmount represents an amount of Telegram Stars.
+// Since: Bot API 7.5
 type StarAmount struct {
 	Amount         int `json:"amount"`
 	NanostarAmount int `json:"nanostar_amount"`
 }
 
-// Story represents a story.
-type Story struct {
-	Chat Chat `json:"chat"`
-	ID   int  `json:"id"`
-}
-
 // AcceptedGiftTypes represents the types of gifts accepted by a user or chat.
+// Since: Bot API 9.0
 type AcceptedGiftTypes struct {
 	UnlimitedGifts      bool `json:"unlimited_gifts"`
 	LimitedGifts        bool `json:"limited_gifts"`
@@ -373,17 +322,8 @@ type AcceptedGiftTypes struct {
 	GiftsFromChannels   bool `json:"gifts_from_channels"`
 }
 
-// UniqueGiftColors represents color information for a unique gift.
-type UniqueGiftColors struct {
-	ModelCustomEmojiID    string `json:"model_custom_emoji_id"`
-	SymbolCustomEmojiID   string `json:"symbol_custom_emoji_id"`
-	LightThemeMainColor   int    `json:"light_theme_main_color"`
-	LightThemeOtherColors []int  `json:"light_theme_other_colors"`
-	DarkThemeMainColor    int    `json:"dark_theme_main_color"`
-	DarkThemeOtherColors  []int  `json:"dark_theme_other_colors"`
-}
-
 // GiftBackground represents the background of a gift.
+// Since: Bot API 9.0
 type GiftBackground struct {
 	CenterColor int `json:"center_color"`
 	EdgeColor   int `json:"edge_color"`
@@ -391,6 +331,7 @@ type GiftBackground struct {
 }
 
 // Gift represents a gift that can be sent.
+// Since: Bot API 9.0
 type Gift struct {
 	ID                     string          `json:"id"`
 	Sticker                Sticker         `json:"sticker"`
@@ -408,11 +349,104 @@ type Gift struct {
 }
 
 // Gifts represents a list of gifts.
+// Since: Bot API 9.0
 type Gifts struct {
 	Gifts []Gift `json:"gifts"`
 }
 
+// UniqueGiftModel describes the model component of a unique gift.
+// Since: Bot API 9.0
+type UniqueGiftModel struct {
+	Name           string  `json:"name"`
+	Sticker        Sticker `json:"sticker"`
+	RarityPerMille int     `json:"rarity_per_mille"`
+	Rarity         string  `json:"rarity,omitempty"`
+}
+
+// UniqueGiftSymbol describes the symbol component of a unique gift.
+// Since: Bot API 9.0
+type UniqueGiftSymbol struct {
+	Name           string  `json:"name"`
+	Sticker        Sticker `json:"sticker"`
+	RarityPerMille int     `json:"rarity_per_mille"`
+}
+
+// UniqueGiftBackdropColors describes the colors of a unique gift backdrop.
+// Since: Bot API 9.0
+type UniqueGiftBackdropColors struct {
+	CenterColor int `json:"center_color"`
+	EdgeColor   int `json:"edge_color"`
+	SymbolColor int `json:"symbol_color"`
+	TextColor   int `json:"text_color"`
+}
+
+// UniqueGiftBackdrop describes the backdrop of a unique gift.
+// Since: Bot API 9.0
+type UniqueGiftBackdrop struct {
+	Name           string                   `json:"name"`
+	Colors         UniqueGiftBackdropColors `json:"colors"`
+	RarityPerMille int                      `json:"rarity_per_mille"`
+}
+
+// UniqueGiftColors represents color information for a unique gift.
+// Since: Bot API 9.3
+type UniqueGiftColors struct {
+	ModelCustomEmojiID    string `json:"model_custom_emoji_id"`
+	SymbolCustomEmojiID   string `json:"symbol_custom_emoji_id"`
+	LightThemeMainColor   int    `json:"light_theme_main_color"`
+	LightThemeOtherColors []int  `json:"light_theme_other_colors"`
+	DarkThemeMainColor    int    `json:"dark_theme_main_color"`
+	DarkThemeOtherColors  []int  `json:"dark_theme_other_colors"`
+}
+
+// UniqueGift represents a unique gift.
+// Since: Bot API 9.0
+type UniqueGift struct {
+	GiftID   string             `json:"gift_id"`
+	BaseName string             `json:"base_name"`
+	Name     string             `json:"name"`
+	Number   int                `json:"number"`
+	Model    UniqueGiftModel    `json:"model"`
+	Symbol   UniqueGiftSymbol   `json:"symbol"`
+	Backdrop UniqueGiftBackdrop `json:"backdrop"`
+
+	IsPremium        bool              `json:"is_premium,omitempty"`
+	IsBurned         bool              `json:"is_burned,omitempty"`
+	IsFromBlockchain bool              `json:"is_from_blockchain,omitempty"`
+	Colors           *UniqueGiftColors `json:"colors,omitempty"`
+	PublisherChat    *Chat             `json:"publisher_chat,omitempty"`
+}
+
+// GiftInfo contains information about a received gift.
+// Since: Bot API 9.0
+type GiftInfo struct {
+	Gift Gift `json:"gift"`
+
+	OwnedGiftID             string          `json:"owned_gift_id,omitempty"`
+	ConvertStarCount        int             `json:"convert_star_count,omitempty"`
+	PrepaidUpgradeStarCount int             `json:"prepaid_upgrade_star_count,omitempty"`
+	IsUpgradeSeparate       bool            `json:"is_upgrade_separate,omitempty"`
+	CanBeUpgraded           bool            `json:"can_be_upgraded,omitempty"`
+	Text                    string          `json:"text,omitempty"`
+	Entities                []MessageEntity `json:"entities,omitempty"`
+	IsPrivate               bool            `json:"is_private,omitempty"`
+	UniqueGiftNumber        int             `json:"unique_gift_number,omitempty"`
+}
+
+// UniqueGiftInfo contains information about a received unique gift.
+// Since: Bot API 9.0
+type UniqueGiftInfo struct {
+	Gift               UniqueGift `json:"gift"`
+	Origin             string     `json:"origin"`
+	LastResaleCurrency string     `json:"last_resale_currency,omitempty"`
+	LastResaleAmount   int        `json:"last_resale_amount,omitempty"`
+	OwnedGiftID        string     `json:"owned_gift_id,omitempty"`
+	TransferStarCount  int        `json:"transfer_star_count,omitempty"`
+	NextTransferDate   int        `json:"next_transfer_date,omitempty"`
+}
+
 // OwnedGiftType represents the type of an owned gift.
+// Since: Bot API 9.0
 type OwnedGiftType string
 
 const (
@@ -423,34 +457,145 @@ const (
 )
 
 // OwnedGift represents a gift owned by a user or chat.
+// Since: Bot API 9.0
 type OwnedGift struct {
 	Type        OwnedGiftType `json:"type"`
-	OwnerGiftID *string       `json:"owner_gift_id,omitempty"`
+	OwnedGiftID string        `json:"ownen_gift_id,omitempty"`
-	SendDate    *int          `json:"send_date,omitempty"`
+	SendDate    int           `json:"send_date,omitempty"`
-	IsSaved     *bool         `json:"is_saved,omitempty"`
+	IsSaved     bool          `json:"is_saved,omitempty"`
 
 	// Fields specific to "regular" type
 	Gift                    Gift            `json:"gift"`
 	SenderUser              *User           `json:"sender_user,omitempty"`
 	Text                    string          `json:"text,omitempty"`
 	Entities                []MessageEntity `json:"entities,omitempty"`
-	IsPrivate               *bool           `json:"is_private,omitempty"`
+	IsPrivate               bool            `json:"is_private,omitempty"`
-	CanBeUpgraded           *bool           `json:"can_be_upgraded,omitempty"`
+	CanBeUpgraded           bool            `json:"can_be_upgraded,omitempty"`
-	WasRefunded             *bool           `json:"was_refunded,omitempty"`
+	WasRefunded             bool            `json:"was_refunded,omitempty"`
-	ConvertStarCount        *int            `json:"convert_star_count,omitempty"`
+	ConvertStarCount        int             `json:"convert_star_count,omitempty"`
-	PrepaidUpgradeStarCount *int            `json:"prepaid_upgrade_star_count,omitempty"`
+	PrepaidUpgradeStarCount int             `json:"prepaid_upgrade_star_count,omitempty"`
-	IsUpgradeSeparate       *bool           `json:"is_upgrade_separate,omitempty"`
+	IsUpgradeSeparate       bool            `json:"is_upgrade_separate,omitempty"`
-	UniqueGiftNumber        *int            `json:"unique_gift_number,omitempty"`
+	UniqueGiftNumber        int             `json:"unique_gift_number,omitempty"`
 
 	// Fields specific to "unique" type
-	CanBeTransferred  *bool `json:"can_be_transferred,omitempty"`
+	CanBeTransferred  bool `json:"can_be_transferred,omitempty"`
-	TransferStarCount *int  `json:"transfer_star_count,omitempty"`
+	TransferStarCount int  `json:"transfer_star_count,omitempty"`
-	NextTransferDate  *int  `json:"next_transfer_date,omitempty"`
+	NextTransferDate  int  `json:"next_transfer_date,omitempty"`
 }
 
 // OwnedGifts represents a list of owned gifts with pagination.
+// Since: Bot API 9.0
 type OwnedGifts struct {
 	TotalCount int         `json:"total_count"`
 	Gifts      []OwnedGift `json:"gifts"`
 	NextOffset string      `json:"next_offset"`
 }
+
+// GiveawayCreated represents a service message about a giveaway being created.
+// Since: Bot API 7.0
+type GiveawayCreated struct {
+	PrizeStarCount int `json:"prize_star_count,omitempty"`
+}
+
+// Giveaway represents a message about a scheduled giveaway.
+// Since: Bot API 7.0
+type Giveaway struct {
+	Chats                []Chat `json:"chats"`
+	WinnersSelectionDate int    `json:"winners_selection_date"`
+	WinnerCount          int    `json:"winner_count"`
+
+	OnlyNewMembers                bool     `json:"only_new_members,omitempty"`
+	HasPublicWinners              bool     `json:"has_public_winners,omitempty"`
+	PrizeDescription              string   `json:"prize_description,omitempty"`
+	CountryCodes                  []string `json:"country_codes,omitempty"`
+	PrizeStarCount                int      `json:"prize_star_count,omitempty"`
+	PremiumSubscriptionMonthCount int      `json:"premium_subscription_month_count,omitempty"`
+}
+
+// GiveawayWinners represents a message about the completion of a giveaway with public winners.
+// Since: Bot API 7.0
+type GiveawayWinners struct {
+	Chat                 Chat   `json:"chat"`
+	GiveawayMessageID    int    `json:"giveaway_message_id"`
+	WinnersSelectionDate int    `json:"winners_selection_date"`
+	WinnerCount          int    `json:"winner_count"`
+	Winners              []User `json:"winners"`
+
+	AdditionalChatCount           int    `json:"additional_chat_count,omitempty"`
+	PrizeStarCount                int    `json:"prize_star_count,omitempty"`
+	PremiumSubscriptionMonthCount int    `json:"premium_subscription_month_count,omitempty"`
+	UnclaimedPrizeCount           int    `json:"unclaimed_prize_count,omitempty"`
+	OnlyNewMembers                bool   `json:"only_new_members,omitempty"`
+	WasRefunded                   bool   `json:"was_refunded,omitempty"`
+	PrizeDescription              string `json:"prize_description,omitempty"`
+}
+
+// GiveawayCompleted represents a service message about the completion of a giveaway without public winners.
+// Since: Bot API 7.0
+type GiveawayCompleted struct {
+	WinnerCount         int      `json:"winner_count"`
+	UnclaimedPrizeCount int      `json:"unclaimed_prize_count,omitempty"`
+	GiveawayMessage     *Message `json:"giveaway_message,omitempty"`
+	IsStarGiveaway      bool     `json:"is_star_giveaway,omitempty"`
+}
+
+// WriteAccessAllowed represents a service message about a user allowing a bot to write messages.
+// Since: Bot API 6.4
+type WriteAccessAllowed struct {
+	FromRequest        bool   `json:"from_request,omitempty"`
+	WebAppName         string `json:"web_app_name,omitempty"`
+	FromAttachmentMenu bool   `json:"from_attachment_menu,omitempty"`
+}
+
+// BackgroundFillType represents the type of a background fill.
+// Since: Bot API 7.5
+type BackgroundFillType string
+
+const (
+	BackgroundFillSolidType            BackgroundFillType = "solid"
+	BackgroundFillGradientType         BackgroundFillType = "gradient"
+	BackgroundFillFreeformGradientType BackgroundFillType = "freeform_gradient"
+)
+
+// BackgroundFill describes the way a background is filled.
+// Since: Bot API 7.5
+type BackgroundFill struct {
+	Type BackgroundFillType `json:"type"`
+
+	Color int `json:"color,omitempty"`
+
+	TopColor      int `json:"top_color,omitempty"`
+	BottomColor   int `json:"bottom_color,omitempty"`
+	RotationAngle int `json:"rotation_angle,omitempty"`
+
+	Colors []int `json:"colors,omitempty"`
+}
+
+// BackgroundTypeType represents the type of a chat background.
+// Since: Bot API 7.5
+type BackgroundTypeType string
+
+const (
+	BackgroundTypeFillType      BackgroundTypeType = "fill"
+	BackgroundTypeWallpaperType BackgroundTypeType = "wallpaper"
+	BackgroundTypePatternType   BackgroundTypeType = "pattern"
+	BackgroundTypeChatThemeType BackgroundTypeType = "chat_theme"
+)
+
+// BackgroundType describes the type of a background.
+// Since: Bot API 7.5
+type BackgroundType struct {
+	Type BackgroundTypeType `json:"type"`
+
+	Fill             *BackgroundFill `json:"fill,omitempty"`
+	DarkThemeDimming int             `json:"dark_theme_dimming,omitempty"`
+
+	Document  *Document `json:"document,omitempty"`
+	IsBlurred bool      `json:"is_blurred,omitempty"`
+	IsMoving  bool      `json:"is_moving,omitempty"`
+
+	Intensity  int  `json:"intensity,omitempty"`
+	IsInverted bool `json:"is_inverted,omitempty"`
+
+	ThemeName string `json:"theme_name,omitempty"`
+}

tgapi/types_test.go

@@ -61,6 +61,17 @@ func TestUpdateUnmarshalSetsType(t *testing.T) {
 			body: `{"update_id":4}`,
 			want: UpdateTypeUnknown,
 		},
+		{
+			name: "managed bot",
+			body: `{
+				"update_id": 5,
+				"managed_bot": {
+					"user": {"id": 11, "is_bot": false, "first_name": "Manager"},
+					"bot": {"id": 12, "is_bot": true, "first_name": "Worker"}
+				}
+			}`,
+			want: UpdateTypeManagedBot,
+		},
 	}
 
 	for _, tt := range tests {
@@ -75,10 +86,41 @@ func TestUpdateUnmarshalSetsType(t *testing.T) {
 			if tt.want == UpdateTypeChatBoost && update.ChatBoost.Boost.BoostID != "boost-1" {
 				t.Fatalf("unexpected boost id: got %q want %q", update.ChatBoost.Boost.BoostID, "boost-1")
 			}
+			if tt.want == UpdateTypeManagedBot && update.ManagedBot.Bot.ID != 12 {
+				t.Fatalf("unexpected managed bot id: got %d want %d", update.ManagedBot.Bot.ID, 12)
+			}
 		})
 	}
 }
 
+func TestPollUnmarshalSupportsBotAPI96Fields(t *testing.T) {
+	var poll Poll
+
+	body := `{
+		"id": "poll-1",
+		"question": "Pick winners",
+		"question_entities": [],
+		"options": [],
+		"total_voter_count": 2,
+		"is_closed": false,
+		"is_anonymous": false,
+		"type": "quiz",
+		"allows_multiple_answers": true,
+		"allows_revoting": true,
+		"correct_option_ids": [1, 3]
+	}`
+
+	if err := json.Unmarshal([]byte(body), &poll); err != nil {
+		t.Fatalf("Unmarshal returned error: %v", err)
+	}
+	if !poll.AllowsRevoting {
+		t.Fatal("expected allows_revoting to be decoded")
+	}
+	if len(poll.CorrectOptionIDs) != 2 || poll.CorrectOptionIDs[0] != 1 || poll.CorrectOptionIDs[1] != 3 {
+		t.Fatalf("unexpected correct option ids: %#v", poll.CorrectOptionIDs)
+	}
+}
+
 func TestUpdateMarshalOmitsSyntheticTypeField(t *testing.T) {
 	update := Update{
 		UpdateID: 1,
@@ -114,3 +156,62 @@ func TestUpdateShippingQueryIsNilWhenAbsent(t *testing.T) {
 		t.Fatalf("expected UpdateTypeUnknown, got %q", update.Type)
 	}
 }
+
+func TestMaybeInaccessibleMessageUnmarshalAccessibleMessage(t *testing.T) {
+	var wrapper MaybeInaccessibleMessage
+
+	body := `{
+		"message_id": 10,
+		"date": 1700000000,
+		"chat": {"id": 42, "type": "private"},
+		"text": "hello"
+	}`
+
+	if err := json.Unmarshal([]byte(body), &wrapper); err != nil {
+		t.Fatalf("Unmarshal returned error: %v", err)
+	}
+	if !wrapper.IsAccessible() {
+		t.Fatal("expected accessible message payload")
+	}
+	if wrapper.IsInaccessible() {
+		t.Fatal("expected inaccessible payload to be empty")
+	}
+	if wrapper.Message() == nil || wrapper.Message().Text != "hello" {
+		t.Fatalf("unexpected accessible payload: %#v", wrapper.Message())
+	}
+	if wrapper.MessageID() != 10 {
+		t.Fatalf("unexpected message id: got %d want %d", wrapper.MessageID(), 10)
+	}
+	if wrapper.Chat() == nil || wrapper.Chat().ID != 42 {
+		t.Fatalf("unexpected chat payload: %#v", wrapper.Chat())
+	}
+}
+
+func TestMaybeInaccessibleMessageUnmarshalInaccessibleMessage(t *testing.T) {
+	var wrapper MaybeInaccessibleMessage
+
+	body := `{
+		"message_id": 7,
+		"date": 0,
+		"chat": {"id": -1001, "type": "supergroup"}
+	}`
+
+	if err := json.Unmarshal([]byte(body), &wrapper); err != nil {
+		t.Fatalf("Unmarshal returned error: %v", err)
+	}
+	if wrapper.IsAccessible() {
+		t.Fatal("expected accessible payload to be empty")
+	}
+	if !wrapper.IsInaccessible() {
+		t.Fatal("expected inaccessible message payload")
+	}
+	if wrapper.InaccessibleMessage() == nil || wrapper.InaccessibleMessage().MessageID != 7 {
+		t.Fatalf("unexpected inaccessible payload: %#v", wrapper.InaccessibleMessage())
+	}
+	if wrapper.MessageID() != 7 {
+		t.Fatalf("unexpected message id: got %d want %d", wrapper.MessageID(), 7)
+	}
+	if wrapper.Chat() == nil || wrapper.Chat().ID != -1001 {
+		t.Fatalf("unexpected chat payload: %#v", wrapper.Chat())
+	}
+}

tgapi/uploader_api.go

@@ -10,8 +10,8 @@ import (
 	"strings"
 	"time"
 
-	"git.nix13.pw/scuroneko/laniakea/utils"
+	"git.scuroneko.dev/scuroneko/laniakea/utils"
-	"git.nix13.pw/scuroneko/slog"
+	"git.scuroneko.dev/scuroneko/sneklog/v2"
 )
 
 const (
@@ -33,6 +33,8 @@ const (
 	UploaderStickerType UploaderFileType = "sticker"
 	// UploaderCertificateType is the multipart field name for webhook certificate uploads.
 	UploaderCertificateType UploaderFileType = "certificate"
+	// UploaderLivePhotoType is the multipart field name for live photo uploads.
+	UploaderLivePhotoType UploaderFileType = "live_photo"
 )
 
 // UploaderFileType represents the Telegram form field name for a file upload.
@@ -65,12 +67,19 @@ func (f UploaderFile) SetType(t UploaderFileType) UploaderFile {
 // (InputFile/multipart). For JSON-only calls (file_id, URL, plain params), use API.
 type Uploader struct {
 	api    *API
-	logger *slog.Logger
+	logger *sneklog.Logger
 }
 
 // NewUploader creates a multipart uploader bound to an API client.
 func NewUploader(api *API) *Uploader {
-	logger := utils.CreateLogger("UPLOADER", utils.GetLoggerLevel())
+	if api == nil {
+		return nil
+	}
+	logger := utils.CreateLogger(
+		"UPLOADER", utils.GetLoggerLevel(),
+		api.logFormat, api.logFormatter,
+	)
+	logger.AddReplacer(api.token, "<TOKEN>")
 	return &Uploader{api, logger}
 }
 
@@ -80,7 +89,7 @@ func (u *Uploader) Close() error { return u.logger.Close() }
 
 // GetLogger returns uploader logger instance.
 // See https://core.telegram.org/bots/api
-func (u *Uploader) GetLogger() *slog.Logger { return u.logger }
+func (u *Uploader) GetLogger() *sneklog.Logger { return u.logger }
 
 // UploaderRequest is a low-level multipart upload request wrapper.
 //
@@ -92,18 +101,18 @@ type UploaderRequest[R, P any] struct {
 	method string
 	files  []UploaderFile
 	params P
-	chatId int64
+	chatID int64
 }
 
 // NewUploaderRequest creates a low-level multipart upload request with no associated chat ID.
 func NewUploaderRequest[R, P any](method string, params P, files ...UploaderFile) UploaderRequest[R, P] {
-	return UploaderRequest[R, P]{method: method, files: files, params: params, chatId: 0}
+	return UploaderRequest[R, P]{method: method, files: files, params: params, chatID: 0}
 }
 
 // NewUploaderRequestWithChatID creates a low-level multipart upload request with an associated chat ID.
 // The chat ID is used for per-chat rate limiting.
-func NewUploaderRequestWithChatID[R, P any](method string, params P, chatId int64, files ...UploaderFile) UploaderRequest[R, P] {
+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}
+	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) {
@@ -113,11 +122,11 @@ func (r UploaderRequest[R, P]) doRequest(ctx context.Context, up *Uploader) (R,
 	if up.api.useTestServer {
 		methodPrefix = "/test"
 	}
-	url := fmt.Sprintf("%s/bot%s%s/%s", up.api.apiUrl, up.api.token, methodPrefix, r.method)
+	url := fmt.Sprintf("%s/bot%s%s/%s", up.api.apiURL, up.api.token, methodPrefix, r.method)
 
 	for {
 		if up.api.Limiter != nil {
-			if err := up.api.Limiter.Check(ctx, up.api.dropOverflowLimit, r.chatId); err != nil {
+			if err := up.api.Limiter.Check(ctx, up.api.dropOverflowLimit, r.chatID); err != nil {
 				return zero, err
 			}
 		}
@@ -135,7 +144,7 @@ func (r UploaderRequest[R, P]) doRequest(ctx context.Context, up *Uploader) (R,
 		req.Header.Set("User-Agent", fmt.Sprintf("Laniakea/%s", utils.VersionString))
 		req.ContentLength = int64(buf.Len())
 
-		up.logger.Debugln("UPLOADER REQ", r.method)
+		up.logger.Debugln("UPLOADER REQ", url)
 		resp, err := up.api.client.Do(req)
 		if err != nil {
 			return zero, err
@@ -146,7 +155,7 @@ func (r UploaderRequest[R, P]) doRequest(ctx context.Context, up *Uploader) (R,
 		if err != nil {
 			return zero, err
 		}
-		up.logger.Debugln("UPLOADER RES", r.method, string(body))
+		up.logger.Debugln("UPLOADER RES", url, string(body))
 
 		response, err := parseBody[R](body)
 		if err != nil {
@@ -156,10 +165,10 @@ func (r UploaderRequest[R, P]) doRequest(ctx context.Context, up *Uploader) (R,
 		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)
+				up.logger.Warnf("Rate limited, retry after %d seconds (chat: %d)", after, r.chatID)
 				if up.api.Limiter != nil {
-					if r.chatId > 0 {
+					if r.chatID > 0 {
-						up.api.Limiter.SetChatLock(r.chatId, after)
+						up.api.Limiter.SetChatLock(r.chatID, after)
 					} else {
 						up.api.Limiter.SetGlobalLock(after)
 					}
@@ -169,10 +178,14 @@ func (r UploaderRequest[R, P]) doRequest(ctx context.Context, up *Uploader) (R,
 				case <-ctx.Done():
 					return zero, ctx.Err()
 				case <-time.After(time.Duration(after) * time.Second):
-					continue // Повторяем запрос
+					continue
 				}
 			}
-			return zero, fmt.Errorf("[%d] %s", response.ErrorCode, response.Description)
+			return zero, &ResponseError{
+				Code:        response.ErrorCode,
+				Description: response.Description,
+				Parameters:  response.Parameters,
+			}
 		}
 		return response.Result, nil
 	}
@@ -210,7 +223,6 @@ func (r UploaderRequest[R, P]) Do(up *Uploader) (R, error) {
 	return r.DoWithContext(context.Background(), up)
 }
 
-// Internal helper that builds a finalized multipart body from files and params.
 func prepareMultipart[P any](files []UploaderFile, params P) (*bytes.Buffer, string, error) {
 	buf := bytes.NewBuffer(nil)
 	w := multipart.NewWriter(buf)
@@ -218,7 +230,7 @@ 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 nil, "", err
 		}
 
@@ -229,13 +241,13 @@ func prepareMultipart[P any](files []UploaderFile, params P) (*bytes.Buffer, str
 		}
 	}
 
-	err := utils.Encode(w, params) // Предполагается, что это записывает в w
+	err := utils.Encode(w, params)
 	if err != nil {
 		_ = w.Close()
 		return nil, "", err
 	}
 
-	err = w.Close() // ✅ ОБЯЗАТЕЛЬНО вызвать в конце — иначе запрос битый!
+	err = w.Close()
 	if err != nil {
 		return nil, "", err
 	}
@@ -243,7 +255,6 @@ func prepareMultipart[P any](files []UploaderFile, params P) (*bytes.Buffer, str
 	return buf, w.FormDataContentType(), nil
 }
 
-// Internal helper that infers an upload field name from a file extension.
 func uploaderTypeByExt(filename string) UploaderFileType {
 	ext := strings.ToLower(filepath.Ext(filename))
 	switch ext {

tgapi/uploader_api_test.go

@@ -1,6 +1,7 @@
 package tgapi
 
 import (
+	"errors"
 	"fmt"
 	"io"
 	"mime"
@@ -40,7 +41,7 @@ func TestUploaderEncodesJSONFieldsAndLeavesAcceptEncodingToHTTPTransport(t *test
 
 	api := NewAPI(
 		NewAPIOpts("token").
-			SetAPIUrl("https://example.test").
+			SetAPIURL("https://example.test").
 			SetHTTPClient(client),
 	)
 	defer func() {
@@ -57,7 +58,7 @@ func TestUploaderEncodesJSONFieldsAndLeavesAcceptEncodingToHTTPTransport(t *test
 	}()
 
 	msg, err := uploader.SendPhoto(
-		UploadPhotoP{
+		UploadPhoto{
 			ChatID: 42,
 			CaptionEntities: []MessageEntity{{
 				Type:   MessageEntityBold,
@@ -104,6 +105,57 @@ func TestUploaderEncodesJSONFieldsAndLeavesAcceptEncodingToHTTPTransport(t *test
 	}
 }
 
+func TestUploaderSurfacesResponseErrorForTelegramFailure(t *testing.T) {
+	const responseBody = `{"ok":false,"error_code":400,"description":"Bad Request: chat not found"}`
+
+	client := &http.Client{
+		Transport: roundTripFunc(func(_ *http.Request) (*http.Response, error) {
+			return &http.Response{
+				StatusCode: http.StatusOK,
+				Header:     http.Header{"Content-Type": []string{"application/json"}},
+				Body:       io.NopCloser(strings.NewReader(responseBody)),
+			}, nil
+		}),
+	}
+
+	api := NewAPI(
+		NewAPIOpts("token").
+			SetAPIURL("https://example.test").
+			SetHTTPClient(client),
+	)
+	defer func() {
+		if err := api.Close(); err != nil {
+			t.Fatalf("Close returned error: %v", err)
+		}
+	}()
+
+	uploader := NewUploader(api)
+	defer func() {
+		if err := uploader.Close(); err != nil {
+			t.Fatalf("Close returned error: %v", err)
+		}
+	}()
+
+	_, err := uploader.SendPhoto(
+		UploadPhoto{ChatID: 42},
+		NewUploaderFile("photo.jpg", []byte("img")),
+	)
+	if err == nil {
+		t.Fatal("expected error, got nil")
+	}
+
+	var respErr *ResponseError
+	if !errors.As(err, &respErr) {
+		t.Fatalf("expected *ResponseError, got %T: %v", err, err)
+	}
+	if respErr.Code != 400 {
+		t.Fatalf("unexpected ResponseError.Code: got %d want 400", respErr.Code)
+	}
+	if !strings.Contains(respErr.Description, "chat not found") {
+		t.Fatalf("unexpected ResponseError.Description: %q", respErr.Description)
+	}
+}
+
 func TestNewUploaderFileDetectsFileTypeCaseInsensitively(t *testing.T) {
 	tests := []struct {
 		name     string

tgapi/uploader_methods.go

@@ -2,9 +2,10 @@ package tgapi
 
 import "context"
 
-// UploadPhotoP holds parameters for uploading a photo using the Uploader.
+// UploadPhoto holds parameters for uploading a photo using the Uploader.
+// Since: Bot API 1.0
 // See https://core.telegram.org/bots/api#sendphoto
-type UploadPhotoP struct {
+type UploadPhoto struct {
 	BusinessConnectionID  string `json:"business_connection_id,omitempty"`
 	ChatID                int64  `json:"chat_id"`
 	MessageThreadID       int    `json:"message_thread_id,omitempty"`
@@ -27,26 +28,27 @@ type UploadPhotoP struct {
 }
 
 // SendPhoto uploads a photo via multipart and sends it as a message.
+// Since: Bot API 1.0
 // file is the photo file to upload.
 // See https://core.telegram.org/bots/api#sendphoto
-func (u *Uploader) SendPhoto(params UploadPhotoP, file UploaderFile) (Message, error) {
+func (u *Uploader) SendPhoto(params UploadPhoto, file UploaderFile) (Message, error) {
 	req := NewUploaderRequestWithChatID[Message]("sendPhoto", params, params.ChatID, file)
 	return req.Do(u)
 }
 
 // SendPhotoWithContext is the context-aware variant of SendPhoto.
-// It executes the same request but uses ctx for cancellation and deadlines.
+// Since: Bot API 1.0
-// SendPhotoWithContext is the context-aware variant of SendPhoto.
 // It executes the same request but uses ctx for cancellation and deadlines.
 // See https://core.telegram.org/bots/api#sendphoto
-func (u *Uploader) SendPhotoWithContext(ctx context.Context, params UploadPhotoP, file UploaderFile) (Message, error) {
+func (u *Uploader) SendPhotoWithContext(ctx context.Context, params UploadPhoto, file UploaderFile) (Message, error) {
 	req := NewUploaderRequestWithChatID[Message]("sendPhoto", params, params.ChatID, file)
 	return req.DoWithContext(ctx, u)
 }
 
-// UploadAudioP holds parameters for uploading an audio file using the Uploader.
+// UploadAudio holds parameters for uploading an audio file using the Uploader.
+// Since: Bot API 1.2
 // See https://core.telegram.org/bots/api#sendaudio
-type UploadAudioP struct {
+type UploadAudio struct {
 	BusinessConnectionID  string `json:"business_connection_id,omitempty"`
 	ChatID                int64  `json:"chat_id"`
 	MessageThreadID       int    `json:"message_thread_id,omitempty"`
@@ -71,26 +73,27 @@ type UploadAudioP struct {
 }
 
 // SendAudio uploads an audio file via multipart and sends it as a message.
+// Since: Bot API 1.2
 // files are the audio file(s) to upload (typically one file).
 // See https://core.telegram.org/bots/api#sendaudio
-func (u *Uploader) SendAudio(params UploadAudioP, files ...UploaderFile) (Message, error) {
+func (u *Uploader) SendAudio(params UploadAudio, files ...UploaderFile) (Message, error) {
 	req := NewUploaderRequestWithChatID[Message]("sendAudio", params, params.ChatID, files...)
 	return req.Do(u)
 }
 
 // SendAudioWithContext is the context-aware variant of SendAudio.
-// It executes the same request but uses ctx for cancellation and deadlines.
+// Since: Bot API 1.2
-// SendAudioWithContext is the context-aware variant of SendAudio.
 // It executes the same request but uses ctx for cancellation and deadlines.
 // See https://core.telegram.org/bots/api#sendaudio
-func (u *Uploader) SendAudioWithContext(ctx context.Context, params UploadAudioP, files ...UploaderFile) (Message, error) {
+func (u *Uploader) SendAudioWithContext(ctx context.Context, params UploadAudio, files ...UploaderFile) (Message, error) {
 	req := NewUploaderRequestWithChatID[Message]("sendAudio", params, params.ChatID, files...)
 	return req.DoWithContext(ctx, u)
 }
 
-// UploadDocumentP holds parameters for uploading a document using the Uploader.
+// UploadDocument holds parameters for uploading a document using the Uploader.
+// Since: Bot API 1.0
 // See https://core.telegram.org/bots/api#senddocument
-type UploadDocumentP struct {
+type UploadDocument struct {
 	BusinessConnectionID  string `json:"business_connection_id,omitempty"`
 	ChatID                int64  `json:"chat_id"`
 	MessageThreadID       int    `json:"message_thread_id,omitempty"`
@@ -112,26 +115,27 @@ type UploadDocumentP struct {
 }
 
 // SendDocument uploads a document via multipart and sends it as a message.
+// Since: Bot API 1.0
 // files are the document file(s) to upload (typically one file).
 // See https://core.telegram.org/bots/api#senddocument
-func (u *Uploader) SendDocument(params UploadDocumentP, files ...UploaderFile) (Message, error) {
+func (u *Uploader) SendDocument(params UploadDocument, files ...UploaderFile) (Message, error) {
 	req := NewUploaderRequestWithChatID[Message]("sendDocument", params, params.ChatID, files...)
 	return req.Do(u)
 }
 
 // SendDocumentWithContext is the context-aware variant of SendDocument.
-// It executes the same request but uses ctx for cancellation and deadlines.
+// Since: Bot API 1.0
-// SendDocumentWithContext is the context-aware variant of SendDocument.
 // It executes the same request but uses ctx for cancellation and deadlines.
 // See https://core.telegram.org/bots/api#senddocument
-func (u *Uploader) SendDocumentWithContext(ctx context.Context, params UploadDocumentP, files ...UploaderFile) (Message, error) {
+func (u *Uploader) SendDocumentWithContext(ctx context.Context, params UploadDocument, files ...UploaderFile) (Message, error) {
 	req := NewUploaderRequestWithChatID[Message]("sendDocument", params, params.ChatID, files...)
 	return req.DoWithContext(ctx, u)
 }
 
-// UploadVideoP holds parameters for uploading a video using the Uploader.
+// UploadVideo holds parameters for uploading a video using the Uploader.
+// Since: Bot API 1.0
 // See https://core.telegram.org/bots/api#sendvideo
-type UploadVideoP struct {
+type UploadVideo struct {
 	BusinessConnectionID  string `json:"business_connection_id,omitempty"`
 	ChatID                int64  `json:"chat_id"`
 	MessageThreadID       int    `json:"message_thread_id,omitempty"`
@@ -160,26 +164,27 @@ type UploadVideoP struct {
 }
 
 // SendVideo uploads a video via multipart and sends it as a message.
+// Since: Bot API 1.0
 // files are the video file(s) to upload (typically one file).
 // See https://core.telegram.org/bots/api#sendvideo
-func (u *Uploader) SendVideo(params UploadVideoP, files ...UploaderFile) (Message, error) {
+func (u *Uploader) SendVideo(params UploadVideo, files ...UploaderFile) (Message, error) {
 	req := NewUploaderRequestWithChatID[Message]("sendVideo", params, params.ChatID, files...)
 	return req.Do(u)
 }
 
 // SendVideoWithContext is the context-aware variant of SendVideo.
-// It executes the same request but uses ctx for cancellation and deadlines.
+// Since: Bot API 1.0
-// SendVideoWithContext is the context-aware variant of SendVideo.
 // It executes the same request but uses ctx for cancellation and deadlines.
 // See https://core.telegram.org/bots/api#sendvideo
-func (u *Uploader) SendVideoWithContext(ctx context.Context, params UploadVideoP, files ...UploaderFile) (Message, error) {
+func (u *Uploader) SendVideoWithContext(ctx context.Context, params UploadVideo, files ...UploaderFile) (Message, error) {
 	req := NewUploaderRequestWithChatID[Message]("sendVideo", params, params.ChatID, files...)
 	return req.DoWithContext(ctx, u)
 }
 
-// UploadAnimationP holds parameters for uploading an animation using the Uploader.
+// UploadAnimation holds parameters for uploading an animation using the Uploader.
+// Since: Bot API 4.0
 // See https://core.telegram.org/bots/api#sendanimation
-type UploadAnimationP struct {
+type UploadAnimation struct {
 	BusinessConnectionID  string `json:"business_connection_id,omitempty"`
 	ChatID                int64  `json:"chat_id"`
 	MessageThreadID       int    `json:"message_thread_id,omitempty"`
@@ -206,26 +211,27 @@ type UploadAnimationP struct {
 }
 
 // SendAnimation uploads an animation via multipart and sends it as a message.
+// Since: Bot API 4.0
 // files are the animation file(s) to upload (typically one file).
 // See https://core.telegram.org/bots/api#sendanimation
-func (u *Uploader) SendAnimation(params UploadAnimationP, files ...UploaderFile) (Message, error) {
+func (u *Uploader) SendAnimation(params UploadAnimation, files ...UploaderFile) (Message, error) {
 	req := NewUploaderRequestWithChatID[Message]("sendAnimation", params, params.ChatID, files...)
 	return req.Do(u)
 }
 
 // SendAnimationWithContext is the context-aware variant of SendAnimation.
-// It executes the same request but uses ctx for cancellation and deadlines.
+// Since: Bot API 4.0
-// SendAnimationWithContext is the context-aware variant of SendAnimation.
 // It executes the same request but uses ctx for cancellation and deadlines.
 // See https://core.telegram.org/bots/api#sendanimation
-func (u *Uploader) SendAnimationWithContext(ctx context.Context, params UploadAnimationP, files ...UploaderFile) (Message, error) {
+func (u *Uploader) SendAnimationWithContext(ctx context.Context, params UploadAnimation, files ...UploaderFile) (Message, error) {
 	req := NewUploaderRequestWithChatID[Message]("sendAnimation", params, params.ChatID, files...)
 	return req.DoWithContext(ctx, u)
 }
 
-// UploadVoiceP holds parameters for uploading a voice note using the Uploader.
+// UploadVoice holds parameters for uploading a voice note using the Uploader.
+// Since: Bot API 1.2
 // See https://core.telegram.org/bots/api#sendvoice
-type UploadVoiceP struct {
+type UploadVoice struct {
 	BusinessConnectionID  string `json:"business_connection_id,omitempty"`
 	ChatID                int64  `json:"chat_id"`
 	MessageThreadID       int    `json:"message_thread_id,omitempty"`
@@ -247,26 +253,27 @@ type UploadVoiceP struct {
 }
 
 // SendVoice uploads a voice note via multipart and sends it as a message.
+// Since: Bot API 1.2
 // files are the voice file(s) to upload (typically one file).
 // See https://core.telegram.org/bots/api#sendvoice
-func (u *Uploader) SendVoice(params UploadVoiceP, files ...UploaderFile) (Message, error) {
+func (u *Uploader) SendVoice(params UploadVoice, files ...UploaderFile) (Message, error) {
 	req := NewUploaderRequestWithChatID[Message]("sendVoice", params, params.ChatID, files...)
 	return req.Do(u)
 }
 
 // SendVoiceWithContext is the context-aware variant of SendVoice.
-// It executes the same request but uses ctx for cancellation and deadlines.
+// Since: Bot API 1.2
-// SendVoiceWithContext is the context-aware variant of SendVoice.
 // It executes the same request but uses ctx for cancellation and deadlines.
 // See https://core.telegram.org/bots/api#sendvoice
-func (u *Uploader) SendVoiceWithContext(ctx context.Context, params UploadVoiceP, files ...UploaderFile) (Message, error) {
+func (u *Uploader) SendVoiceWithContext(ctx context.Context, params UploadVoice, files ...UploaderFile) (Message, error) {
 	req := NewUploaderRequestWithChatID[Message]("sendVoice", params, params.ChatID, files...)
 	return req.DoWithContext(ctx, u)
 }
 
-// UploadVideoNoteP holds parameters for uploading a video note (rounded video) using the Uploader.
+// UploadVideoNote holds parameters for uploading a video note (rounded video) using the Uploader.
+// Since: Bot API 3.0
 // See https://core.telegram.org/bots/api#sendvideonote
-type UploadVideoNoteP struct {
+type UploadVideoNote struct {
 	BusinessConnectionID  string `json:"business_connection_id,omitempty"`
 	ChatID                int64  `json:"chat_id"`
 	MessageThreadID       int    `json:"message_thread_id,omitempty"`
@@ -286,71 +293,118 @@ type UploadVideoNoteP struct {
 }
 
 // SendVideoNote uploads a video note via multipart and sends it as a message.
+// Since: Bot API 3.0
 // files are the video note file(s) to upload (typically one file).
 // See https://core.telegram.org/bots/api#sendvideonote
-func (u *Uploader) SendVideoNote(params UploadVideoNoteP, files ...UploaderFile) (Message, error) {
+func (u *Uploader) SendVideoNote(params UploadVideoNote, files ...UploaderFile) (Message, error) {
 	req := NewUploaderRequestWithChatID[Message]("sendVideoNote", params, params.ChatID, files...)
 	return req.Do(u)
 }
 
 // SendVideoNoteWithContext is the context-aware variant of SendVideoNote.
-// It executes the same request but uses ctx for cancellation and deadlines.
+// Since: Bot API 3.0
-// SendVideoNoteWithContext is the context-aware variant of SendVideoNote.
 // It executes the same request but uses ctx for cancellation and deadlines.
 // See https://core.telegram.org/bots/api#sendvideonote
-func (u *Uploader) SendVideoNoteWithContext(ctx context.Context, params UploadVideoNoteP, files ...UploaderFile) (Message, error) {
+func (u *Uploader) SendVideoNoteWithContext(ctx context.Context, params UploadVideoNote, files ...UploaderFile) (Message, error) {
 	req := NewUploaderRequestWithChatID[Message]("sendVideoNote", params, params.ChatID, files...)
 	return req.DoWithContext(ctx, u)
 }
 
-// UploadChatPhotoP holds parameters for uploading a chat photo using the Uploader.
+// UploadChatPhoto holds parameters for uploading a chat photo using the Uploader.
+// Since: Bot API 3.1
 // See https://core.telegram.org/bots/api#setchatphoto
-type UploadChatPhotoP struct {
+type UploadChatPhoto struct {
 	ChatID int64 `json:"chat_id"`
 }
 
 // SetChatPhoto uploads a new chat photo.
+// Since: Bot API 3.1
 // photo is the photo file to upload.
 // See https://core.telegram.org/bots/api#setchatphoto
-func (u *Uploader) SetChatPhoto(params UploadChatPhotoP, photo UploaderFile) (bool, error) {
+func (u *Uploader) SetChatPhoto(params UploadChatPhoto, photo UploaderFile) (bool, error) {
 	req := NewUploaderRequestWithChatID[bool]("setChatPhoto", params, params.ChatID, photo)
 	return req.Do(u)
 }
 
 // SetChatPhotoWithContext is the context-aware variant of SetChatPhoto.
-// It executes the same request but uses ctx for cancellation and deadlines.
+// Since: Bot API 3.1
-// SetChatPhotoWithContext is the context-aware variant of SetChatPhoto.
 // It executes the same request but uses ctx for cancellation and deadlines.
 // See https://core.telegram.org/bots/api#setchatphoto
-func (u *Uploader) SetChatPhotoWithContext(ctx context.Context, params UploadChatPhotoP, photo UploaderFile) (bool, error) {
+func (u *Uploader) SetChatPhotoWithContext(ctx context.Context, params UploadChatPhoto, photo UploaderFile) (bool, error) {
 	req := NewUploaderRequestWithChatID[bool]("setChatPhoto", params, params.ChatID, photo)
 	return req.DoWithContext(ctx, u)
 }
 
-// UploadSetWebhookP holds multipart parameters for the setWebhook method.
+// UploadSetWebhook holds multipart parameters for the setWebhook method.
+// Since: Bot API 1.0
 // Use this type when uploading a self-signed certificate file.
 // See https://core.telegram.org/bots/api#setwebhook
-type UploadSetWebhookP struct {
+type UploadSetWebhook struct {
 	URL                string       `json:"url"`
 	IPAddress          string       `json:"ip_address,omitempty"`
-	MaxConnections     int          `json:"max_connections,omitempty"`
+	MaxConnections     int8         `json:"max_connections,omitempty"`
 	AllowedUpdates     []UpdateType `json:"allowed_updates,omitempty"`
 	DropPendingUpdates bool         `json:"drop_pending_updates,omitempty"`
 	SecretToken        string       `json:"secret_token,omitempty"`
 }
 
 // SetWebhook uploads a certificate and sets a webhook URL.
-// certificate maps to the multipart field \"certificate\".
+// Since: Bot API 1.0
+// certificate maps to the multipart field "certificate".
 // See https://core.telegram.org/bots/api#setwebhook
-func (u *Uploader) SetWebhook(params UploadSetWebhookP, certificate UploaderFile) (bool, error) {
+func (u *Uploader) SetWebhook(params UploadSetWebhook, certificate UploaderFile) (bool, error) {
 	req := NewUploaderRequest[bool]("setWebhook", params, certificate.SetType(UploaderCertificateType))
 	return req.Do(u)
 }
 
 // SetWebhookWithContext is the context-aware variant of SetWebhook.
+// Since: Bot API 1.0
 // It executes the same request but uses ctx for cancellation and deadlines.
 // See https://core.telegram.org/bots/api#setwebhook
-func (u *Uploader) SetWebhookWithContext(ctx context.Context, params UploadSetWebhookP, certificate UploaderFile) (bool, error) {
+func (u *Uploader) SetWebhookWithContext(ctx context.Context, params UploadSetWebhook, certificate UploaderFile) (bool, error) {
 	req := NewUploaderRequest[bool]("setWebhook", params, certificate.SetType(UploaderCertificateType))
 	return req.DoWithContext(ctx, u)
 }
+
+// UploadLivePhoto holds parameters for uploading a live photo using the Uploader.
+// Since: Bot API 10.0
+// See https://core.telegram.org/bots/api#sendlivephoto
+type UploadLivePhoto struct {
+	BusinessConnectionID  string `json:"business_connection_id,omitempty"`
+	ChatID                int64  `json:"chat_id"`
+	MessageThreadID       int    `json:"message_thread_id,omitempty"`
+	DirectMessagesTopicID int    `json:"direct_messages_topic_id,omitempty"`
+
+	Caption         string          `json:"caption,omitempty"`
+	ParseMode       ParseMode       `json:"parse_mode,omitempty"`
+	CaptionEntities []MessageEntity `json:"caption_entities,omitempty"`
+
+	ShowCaptionAboveMedia bool   `json:"show_caption_above_media,omitempty"`
+	HasSpoiler            bool   `json:"has_spoiler,omitempty"`
+	DisableNotification   bool   `json:"disable_notification,omitempty"`
+	ProtectContent        bool   `json:"protect_content,omitempty"`
+	AllowPaidBroadcast    bool   `json:"allow_paid_broadcast,omitempty"`
+	MessageEffectID       string `json:"message_effect_id,omitempty"`
+
+	SuggestedPostParameters *SuggestedPostParameters `json:"suggested_post_parameters,omitempty"`
+	ReplyParameters         *ReplyParameters         `json:"reply_parameters,omitempty"`
+	ReplyMarkup             *ReplyMarkup             `json:"reply_markup,omitempty"`
+}
+
+// SendLivePhoto uploads a live photo via multipart and sends it as a message.
+// Since: Bot API 10.0
+// file is the live photo file to upload.
+// See https://core.telegram.org/bots/api#sendlivephoto
+func (u *Uploader) SendLivePhoto(params UploadLivePhoto, file UploaderFile) (Message, error) {
+	req := NewUploaderRequestWithChatID[Message]("sendLivePhoto", params, params.ChatID, file.SetType(UploaderLivePhotoType))
+	return req.Do(u)
+}
+
+// SendLivePhotoWithContext is the context-aware variant of SendLivePhoto.
+// Since: Bot API 10.0
+// It executes the same request but uses ctx for cancellation and deadlines.
+// See https://core.telegram.org/bots/api#sendlivephoto
+func (u *Uploader) SendLivePhotoWithContext(ctx context.Context, params UploadLivePhoto, file UploaderFile) (Message, error) {
+	req := NewUploaderRequestWithChatID[Message]("sendLivePhoto", params, params.ChatID, file.SetType(UploaderLivePhotoType))
+	return req.DoWithContext(ctx, u)
+}

tgapi/users_methods.go

@@ -2,79 +2,89 @@ package tgapi
 
 import "context"
 
-// GetUserProfilePhotosP holds parameters for the GetUserProfilePhotos method.
+// GetUserProfilePhotos holds parameters for the GetUserProfilePhotos method.
+// Since: Bot API 1.4
 // See https://core.telegram.org/bots/api#getuserprofilephotos
-type GetUserProfilePhotosP struct {
+type GetUserProfilePhotos struct {
 	UserID int64 `json:"user_id"`
 	Offset int   `json:"offset,omitempty"`
 	Limit  int   `json:"limit,omitempty"`
 }
 
 // GetUserProfilePhotos returns a list of profile pictures for a user.
+// Since: Bot API 1.4
 // See https://core.telegram.org/bots/api#getuserprofilephotos
-func (api *API) GetUserProfilePhotos(params GetUserProfilePhotosP) (UserProfilePhotos, error) {
+func (api *API) GetUserProfilePhotos(params GetUserProfilePhotos) (UserProfilePhotos, error) {
 	req := NewRequest[UserProfilePhotos]("getUserProfilePhotos", params)
 	return req.Do(api)
 }
 
 // GetUserProfilePhotosWithContext is the context-aware variant of GetUserProfilePhotos.
+// Since: Bot API 1.4
 // It executes the same request but uses ctx for cancellation and deadlines.
 // See https://core.telegram.org/bots/api#getuserprofilephotos
-func (api *API) GetUserProfilePhotosWithContext(ctx context.Context, params GetUserProfilePhotosP) (UserProfilePhotos, error) {
+func (api *API) GetUserProfilePhotosWithContext(ctx context.Context, params GetUserProfilePhotos) (UserProfilePhotos, error) {
 	req := NewRequest[UserProfilePhotos]("getUserProfilePhotos", params)
 	return req.DoWithContext(ctx, api)
 }
 
-// GetUserProfileAudiosP holds parameters for the GetUserProfileAudios method.
+// GetUserProfileAudios holds parameters for the GetUserProfileAudios method.
+// Since: Bot API 9.3
 // See https://core.telegram.org/bots/api#getuserprofileaudios
-type GetUserProfileAudiosP struct {
+type GetUserProfileAudios struct {
 	UserID int64 `json:"user_id"`
 	Offset int   `json:"offset,omitempty"`
 	Limit  int   `json:"limit,omitempty"`
 }
 
 // GetUserProfileAudios returns a list of profile audios for a user.
+// Since: Bot API 9.3
 // See https://core.telegram.org/bots/api#getuserprofileaudios
-func (api *API) GetUserProfileAudios(params GetUserProfileAudiosP) (UserProfileAudios, error) {
+func (api *API) GetUserProfileAudios(params GetUserProfileAudios) (UserProfileAudios, error) {
 	req := NewRequest[UserProfileAudios]("getUserProfileAudios", params)
 	return req.Do(api)
 }
 
 // GetUserProfileAudiosWithContext is the context-aware variant of GetUserProfileAudios.
+// Since: Bot API 9.3
 // It executes the same request but uses ctx for cancellation and deadlines.
 // See https://core.telegram.org/bots/api#getuserprofileaudios
-func (api *API) GetUserProfileAudiosWithContext(ctx context.Context, params GetUserProfileAudiosP) (UserProfileAudios, error) {
+func (api *API) GetUserProfileAudiosWithContext(ctx context.Context, params GetUserProfileAudios) (UserProfileAudios, error) {
 	req := NewRequest[UserProfileAudios]("getUserProfileAudios", params)
 	return req.DoWithContext(ctx, api)
 }
 
-// SetUserEmojiStatusP holds parameters for the SetUserEmojiStatus method.
+// SetUserEmojiStatus holds parameters for the SetUserEmojiStatus method.
+// Since: Bot API 8.0
 // See https://core.telegram.org/bots/api#setuseremojistatus
-type SetUserEmojiStatusP struct {
+type SetUserEmojiStatus struct {
 	UserID         int64  `json:"user_id"`
 	EmojiID        string `json:"emoji_status_custom_emoji_id,omitempty"`
 	ExpirationDate int    `json:"emoji_status_expiration_date,omitempty"`
 }
 
 // SetUserEmojiStatus sets a custom emoji status for a user.
+// Since: Bot API 8.0
 // Returns true on success.
 // See https://core.telegram.org/bots/api#setuseremojistatus
-func (api *API) SetUserEmojiStatus(params SetUserEmojiStatusP) (bool, error) {
+func (api *API) SetUserEmojiStatus(params SetUserEmojiStatus) (bool, error) {
 	req := NewRequest[bool]("setUserEmojiStatus", params)
 	return req.Do(api)
 }
 
 // SetUserEmojiStatusWithContext is the context-aware variant of SetUserEmojiStatus.
+// Since: Bot API 8.0
 // It executes the same request but uses ctx for cancellation and deadlines.
 // See https://core.telegram.org/bots/api#setuseremojistatus
-func (api *API) SetUserEmojiStatusWithContext(ctx context.Context, params SetUserEmojiStatusP) (bool, error) {
+func (api *API) SetUserEmojiStatusWithContext(ctx context.Context, params SetUserEmojiStatus) (bool, error) {
 	req := NewRequest[bool]("setUserEmojiStatus", params)
 	return req.DoWithContext(ctx, api)
 }
 
-// GetUserGiftsP holds parameters for the GetUserGifts method.
+// GetUserGifts holds parameters for the GetUserGifts method.
+// Since: Bot API 9.3
 // See https://core.telegram.org/bots/api#getusergifts
-type GetUserGiftsP struct {
+type GetUserGifts struct {
 	UserID                      int64  `json:"user_id"`
 	ExcludeUnlimited            bool   `json:"exclude_unlimited,omitempty"`
 	ExcludeLimitedUpgradable    bool   `json:"exclude_limited_upgradable,omitempty"`
@@ -87,16 +97,44 @@ type GetUserGiftsP struct {
 }
 
 // GetUserGifts returns gifts owned by a user.
+// Since: Bot API 9.3
 // See https://core.telegram.org/bots/api#getusergifts
-func (api *API) GetUserGifts(params GetUserGiftsP) (OwnedGifts, error) {
+func (api *API) GetUserGifts(params GetUserGifts) (OwnedGifts, error) {
 	req := NewRequest[OwnedGifts]("getUserGifts", params)
 	return req.Do(api)
 }
 
 // GetUserGiftsWithContext is the context-aware variant of GetUserGifts.
+// Since: Bot API 9.3
 // It executes the same request but uses ctx for cancellation and deadlines.
 // See https://core.telegram.org/bots/api#getusergifts
-func (api *API) GetUserGiftsWithContext(ctx context.Context, params GetUserGiftsP) (OwnedGifts, error) {
+func (api *API) GetUserGiftsWithContext(ctx context.Context, params GetUserGifts) (OwnedGifts, error) {
 	req := NewRequest[OwnedGifts]("getUserGifts", params)
 	return req.DoWithContext(ctx, api)
 }
+
+// GetUserPersonalChatMessages holds parameters for the getUserPersonalChatMessages method.
+// Since: Bot API 10.0
+// See https://core.telegram.org/bots/api#getuserpersonalchatmessages
+type GetUserPersonalChatMessages struct {
+	UserID int64 `json:"user_id"`
+	Offset int   `json:"offset,omitempty"`
+	Limit  int   `json:"limit,omitempty"`
+}
+
+// GetUserPersonalChatMessages returns messages from the personal chat of the user with the bot.
+// Since: Bot API 10.0
+// See https://core.telegram.org/bots/api#getuserpersonalchatmessages
+func (api *API) GetUserPersonalChatMessages(params GetUserPersonalChatMessages) ([]Message, error) {
+	req := NewRequest[[]Message]("getUserPersonalChatMessages", params)
+	return req.Do(api)
+}
+
+// GetUserPersonalChatMessagesWithContext is the context-aware variant of GetUserPersonalChatMessages.
+// Since: Bot API 10.0
+// It executes the same request but uses ctx for cancellation and deadlines.
+// See https://core.telegram.org/bots/api#getuserpersonalchatmessages
+func (api *API) GetUserPersonalChatMessagesWithContext(ctx context.Context, params GetUserPersonalChatMessages) ([]Message, error) {
+	req := NewRequest[[]Message]("getUserPersonalChatMessages", params)
+	return req.DoWithContext(ctx, api)
+}

tgapi/users_types.go

@@ -1,26 +1,31 @@
 package tgapi
 
 // User represents a Telegram user or bot.
+// Since: Bot API 1.0
 // See https://core.telegram.org/bots/api#user
 type User struct {
-	ID                        int64   `json:"id"`
+	ID        int64   `json:"id"`
-	IsBot                     bool    `json:"is_bot"`
+	FirstName string  `json:"first_name"`
-	FirstName                 string  `json:"first_name"`
+	LastName  *string `json:"last_name,omitempty"`
-	LastName                  *string `json:"last_name,omitempty"`
+	Username  *string `json:"username,omitempty"`
-	Username                  *string `json:"username,omitempty"`
+
-	LanguageCode              *string `json:"language_code,omitempty"`
+	IsBot                     bool    `json:"is_bot"`                                  // Since: Bot API 3.3
-	IsPremium                 *bool   `json:"is_premium,omitempty"`
+	LanguageCode              *string `json:"language_code,omitempty"`                 // Since: Bot API 3.0
-	AddedToAttachmentMenu     *bool   `json:"added_to_attachment_menu,omitempty"`
+	IsPremium                 *bool   `json:"is_premium,omitempty"`                    // Since: Bot API 6.1
-	CanJoinGroups             *bool   `json:"can_join_groups,omitempty"`
+	AddedToAttachmentMenu     *bool   `json:"added_to_attachment_menu,omitempty"`      // Since: Bot API 6.1
-	CanReadAllGroupMessages   *bool   `json:"can_read_all_group_messages,omitempty"`
+	CanJoinGroups             *bool   `json:"can_join_groups,omitempty"`               // Since: Bot API 4.6
-	SupportsInlineQueries     *bool   `json:"supports_inline_queries,omitempty"`
+	CanReadAllGroupMessages   *bool   `json:"can_read_all_group_messages,omitempty"`   // Since: Bot API 4.6
-	CanConnectToBusiness      *bool   `json:"can_connect_to_business,omitempty"`
+	SupportsInlineQueries     *bool   `json:"supports_inline_queries,omitempty"`       // Since: Bot API 4.6
-	HasMainWebApp             *bool   `json:"has_main_web_app,omitempty"`
+	CanConnectToBusiness      *bool   `json:"can_connect_to_business,omitempty"`       // Since: Bot API 7.2
-	HasTopicsEnabled          *bool   `json:"has_topics_enabled,omitempty"`
+	HasMainWebApp             *bool   `json:"has_main_web_app,omitempty"`              // Since: Bot API 7.8
-	AllowsUsersToCreateTopics *bool   `json:"allows_users_to_create_topics,omitempty"`
+	HasTopicsEnabled          *bool   `json:"has_topics_enabled,omitempty"`            // Since: Bot API 9.3
+	AllowsUsersToCreateTopics *bool   `json:"allows_users_to_create_topics,omitempty"` // Since: Bot API 9.4
+	CanManageBots             *bool   `json:"can_manage_bots,omitempty"`               // Since: Bot API 9.6
+	SupportsGuestQueries      *bool   `json:"supports_guest_queries,omitempty"`        // Since: Bot API 10.0
 }
 
 // UserProfilePhotos represents a user's profile photos.
+// Since: Bot API 1.4
 // See https://core.telegram.org/bots/api#userprofilephotos
 type UserProfilePhotos struct {
 	TotalCount int           `json:"total_count"`
@@ -28,6 +33,7 @@ type UserProfilePhotos struct {
 }
 
 // UserProfileAudios represents a user's profile audios.
+// Since: Bot API 9.3
 // See https://core.telegram.org/bots/api#userprofileaudios
 type UserProfileAudios struct {
 	TotalCount int     `json:"total_count"`
@@ -35,6 +41,7 @@ type UserProfileAudios struct {
 }
 
 // UserRating represents a user's rating with level progression.
+// Since: Bot API 9.3
 // See https://core.telegram.org/bots/api#userrating
 type UserRating struct {
 	Level              int `json:"level"`
@@ -44,6 +51,7 @@ type UserRating struct {
 }
 
 // Birthdate represents a user's birthdate.
+// Since: Bot API 7.2
 // See https://core.telegram.org/bots/api#birthdate
 type Birthdate struct {
 	Day   int `json:"day"`

tgfmt/doc.go

@@ -0,0 +1,2 @@
+// Package tgfmt provides small helpers for Telegram text formatting.
+package tgfmt

tgfmt/html.go

@@ -0,0 +1,99 @@
+package tgfmt
+
+import (
+	"strconv"
+	"strings"
+)
+
+// HTML is an escaped Telegram HTML fragment.
+//
+// Methods on HTML compose formatting without escaping the fragment again.
+type HTML string
+
+// EscapeHTML escapes special characters for Telegram HTML parse mode.
+func EscapeHTML(s string) HTML {
+	s = strings.ReplaceAll(s, "&", "&")
+	s = strings.ReplaceAll(s, "<", "&lt;")
+	s = strings.ReplaceAll(s, ">", "&gt;")
+	s = strings.ReplaceAll(s, `"`, "&quot;")
+	return HTML(s)
+}
+
+// Bold returns h wrapped as bold Telegram HTML text.
+func (h HTML) Bold() HTML {
+	return "<b>" + h + "</b>"
+}
+
+// Italic returns h wrapped as italic Telegram HTML text.
+func (h HTML) Italic() HTML {
+	return "<i>" + h + "</i>"
+}
+
+// Underline returns h wrapped as underlined Telegram HTML text.
+func (h HTML) Underline() HTML {
+	return "<u>" + h + "</u>"
+}
+
+// Strikethrough returns h wrapped as strikethrough Telegram HTML text.
+func (h HTML) Strikethrough() HTML {
+	return "<s>" + h + "</s>"
+}
+
+// Spoiler returns h wrapped as spoiler Telegram HTML text.
+func (h HTML) Spoiler() HTML {
+	return "<tg-spoiler>" + h + "</tg-spoiler>"
+}
+
+// Link returns h as a Telegram HTML text link.
+func (h HTML) Link(url string) HTML {
+	return `<a href="` + escapeHTMLAttr(url) + `">` + h + "</a>"
+}
+
+// Mention returns h as a Telegram HTML user mention.
+func (h HTML) Mention(userID int64) HTML {
+	return `<a href="tg://user?id=` + HTML(strconv.FormatInt(userID, 10)) + `">` + h + "</a>"
+}
+
+// Emoji returns h as a Telegram HTML custom emoji.
+func (h HTML) Emoji(emojiID string) HTML {
+	return `<tg-emoji emoji-id="` + escapeHTMLAttr(emojiID) + `">` + h + "</tg-emoji>"
+}
+
+// Time returns h as a Telegram HTML localized timestamp.
+func (h HTML) Time(unix int64) HTML {
+	return `<tg-time unix="` + HTML(strconv.FormatInt(unix, 10)) + `">` + h + "</tg-time>"
+}
+
+// TimeFormat returns h as a Telegram HTML localized timestamp with format.
+func (h HTML) TimeFormat(unix int64, format string) HTML {
+	return `<tg-time unix="` + HTML(strconv.FormatInt(unix, 10)) + `" format="` + escapeHTMLAttr(format) + `">` + h + "</tg-time>"
+}
+
+// InlineCode returns h wrapped as inline code Telegram HTML text.
+func (h HTML) InlineCode() HTML {
+	return "<code>" + h + "</code>"
+}
+
+// BlockCode returns h wrapped as a Telegram HTML code block.
+func (h HTML) BlockCode() HTML {
+	return "<pre>" + h + "</pre>"
+}
+
+// BlockCodeLanguage returns h wrapped as a Telegram HTML code block with language.
+func (h HTML) BlockCodeLanguage(lang string) HTML {
+	return `<pre><code class="language-` + escapeHTMLAttr(lang) + `">` + h + "</code></pre>"
+}
+
+// Quote returns h as a Telegram HTML blockquote.
+func (h HTML) Quote() HTML {
+	return "<blockquote>" + h + "</blockquote>"
+}
+
+// QuoteExpandable returns h as a Telegram HTML expandable blockquote.
+func (h HTML) QuoteExpandable() HTML {
+	return "<blockquote expandable>" + h + "</blockquote>"
+}
+
+func escapeHTMLAttr(s string) HTML {
+	return EscapeHTML(s)
+}

tgfmt/html_test.go

@@ -0,0 +1,78 @@
+package tgfmt
+
+import "testing"
+
+func TestEscapeHTML(t *testing.T) {
+	got := EscapeHTML(`<tag attr="a&b">`)
+	want := HTML(`&lt;tag attr=&quot;a&amp;b&quot;&gt;`)
+
+	if got != want {
+		t.Fatalf("EscapeHTML() = %q, want %q", got, want)
+	}
+}
+
+func TestHTMLComposesWithoutDoubleEscaping(t *testing.T) {
+	got := EscapeHTML("<b>").Bold().Italic()
+	want := HTML("<i><b>&lt;b&gt;</b></i>")
+
+	if got != want {
+		t.Fatalf("formatted HTML = %q, want %q", got, want)
+	}
+}
+
+func TestHTMLFormattingMethods(t *testing.T) {
+	tests := []struct {
+		name string
+		got  HTML
+		want HTML
+	}{
+		{name: "bold", got: EscapeHTML("text").Bold(), want: "<b>text</b>"},
+		{name: "italic", got: EscapeHTML("text").Italic(), want: "<i>text</i>"},
+		{name: "underline", got: EscapeHTML("text").Underline(), want: "<u>text</u>"},
+		{name: "strikethrough", got: EscapeHTML("text").Strikethrough(), want: "<s>text</s>"},
+		{name: "spoiler", got: EscapeHTML("text").Spoiler(), want: "<tg-spoiler>text</tg-spoiler>"},
+		{name: "inline code", got: EscapeHTML("text").InlineCode(), want: "<code>text</code>"},
+		{name: "block code", got: EscapeHTML("text").BlockCode(), want: "<pre>text</pre>"},
+		{name: "block code language", got: EscapeHTML("text").BlockCodeLanguage(`go"`), want: `<pre><code class="language-go&quot;">text</code></pre>`},
+		{name: "quote", got: EscapeHTML("text").Quote(), want: "<blockquote>text</blockquote>"},
+		{name: "expandable quote", got: EscapeHTML("text").QuoteExpandable(), want: "<blockquote expandable>text</blockquote>"},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			if tt.got != tt.want {
+				t.Fatalf("formatted HTML = %q, want %q", tt.got, tt.want)
+			}
+		})
+	}
+}
+
+func TestHTMLLinkEscapesAttributes(t *testing.T) {
+	got := EscapeHTML("Laniakea").Link(`https://example.test/?q="a&b"`)
+	want := HTML(`<a href="https://example.test/?q=&quot;a&amp;b&quot;">Laniakea</a>`)
+
+	if got != want {
+		t.Fatalf("Link() = %q, want %q", got, want)
+	}
+}
+
+func TestHTMLSpecialLinks(t *testing.T) {
+	tests := []struct {
+		name string
+		got  HTML
+		want HTML
+	}{
+		{name: "mention", got: EscapeHTML("User").Mention(123), want: `<a href="tg://user?id=123">User</a>`},
+		{name: "emoji", got: EscapeHTML("emoji").Emoji(`12"3`), want: `<tg-emoji emoji-id="12&quot;3">emoji</tg-emoji>`},
+		{name: "time", got: EscapeHTML("date").Time(1772323200), want: `<tg-time unix="1772323200">date</tg-time>`},
+		{name: "time format", got: EscapeHTML("date").TimeFormat(1772323200, `MMM " yyyy`), want: `<tg-time unix="1772323200" format="MMM &quot; yyyy">date</tg-time>`},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			if tt.got != tt.want {
+				t.Fatalf("formatted HTML link = %q, want %q", tt.got, tt.want)
+			}
+		})
+	}
+}

tgfmt/md.go

@@ -0,0 +1,56 @@
+package tgfmt
+
+import (
+	"strconv"
+	"strings"
+)
+
+// Markdown is an escaped legacy Telegram Markdown fragment.
+//
+// Deprecated: Use MarkdownV2 instead.
+type Markdown string
+
+// EscapeMarkdown escapes special characters for legacy Telegram Markdown.
+//
+// Deprecated: Use EscapeMarkdownV2 instead.
+func EscapeMarkdown(s string) Markdown {
+	s = strings.ReplaceAll(s, "_", `\_`)
+	s = strings.ReplaceAll(s, "*", `\*`)
+	s = strings.ReplaceAll(s, "[", `\[`)
+	return Markdown(strings.ReplaceAll(s, "`", "\\`"))
+}
+
+// Bold returns s wrapped as bold legacy Telegram Markdown text.
+func (s Markdown) Bold() Markdown {
+	return "*" + s + "*"
+}
+
+// Italic returns s wrapped as italic legacy Telegram Markdown text.
+func (s Markdown) Italic() Markdown {
+	return "_" + s + "_"
+}
+
+// Link returns s as a legacy Telegram Markdown text link.
+func (s Markdown) Link(url string) Markdown {
+	return "[" + s + "](" + Markdown(url) + ")"
+}
+
+// Mention returns s as a legacy Telegram Markdown user mention.
+func (s Markdown) Mention(userID int64) Markdown {
+	return "[" + s + "](tg://user?id=" + Markdown(strconv.FormatInt(userID, 10)) + ")"
+}
+
+// InlineCode returns s wrapped as inline code legacy Telegram Markdown text.
+func (s Markdown) InlineCode() Markdown {
+	return "`" + s + "`"
+}
+
+// BlockCode returns s wrapped as a legacy Telegram Markdown code block.
+func (s Markdown) BlockCode() Markdown {
+	return "```\n" + s + "\n```"
+}
+
+// BlockCodeLanguage returns s wrapped as a legacy Telegram Markdown code block.
+func (s Markdown) BlockCodeLanguage(lang string) Markdown {
+	return "```" + Markdown(lang) + "\n" + s + "\n```"
+}

tgfmt/md_test.go

@@ -0,0 +1,36 @@
+package tgfmt
+
+import "testing"
+
+func TestEscapeMarkdown(t *testing.T) {
+	got := EscapeMarkdown("a_b*c[1]`x`")
+	want := Markdown("a\\_b\\*c\\[1]\\`x\\`")
+
+	if got != want {
+		t.Fatalf("EscapeMarkdown() = %q, want %q", got, want)
+	}
+}
+
+func TestMarkdownFormattingMethods(t *testing.T) {
+	tests := []struct {
+		name string
+		got  Markdown
+		want Markdown
+	}{
+		{name: "bold", got: EscapeMarkdown("text").Bold(), want: "*text*"},
+		{name: "italic", got: EscapeMarkdown("text").Italic(), want: "_text_"},
+		{name: "link", got: EscapeMarkdown("Laniakea").Link("https://example.test"), want: "[Laniakea](https://example.test)"},
+		{name: "mention", got: EscapeMarkdown("User").Mention(123), want: "[User](tg://user?id=123)"},
+		{name: "inline code", got: EscapeMarkdown("text").InlineCode(), want: "`text`"},
+		{name: "block code", got: EscapeMarkdown("text").BlockCode(), want: "```\ntext\n```"},
+		{name: "block code language", got: EscapeMarkdown("text").BlockCodeLanguage("go"), want: "```go\ntext\n```"},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			if tt.got != tt.want {
+				t.Fatalf("formatted Markdown = %q, want %q", tt.got, tt.want)
+			}
+		})
+	}
+}

tgfmt/mdv2.go

@@ -0,0 +1,103 @@
+package tgfmt
+
+import (
+	"strconv"
+	"strings"
+)
+
+// MarkdownV2 is an escaped Telegram MarkdownV2 fragment.
+//
+// Methods on MarkdownV2 compose formatting without escaping the fragment again.
+type MarkdownV2 string
+
+// EscapeMarkdownV2 escapes special characters for Telegram MarkdownV2.
+// https://core.telegram.org/bots/api#markdownv2-style
+func EscapeMarkdownV2(s string) MarkdownV2 {
+	symbols := []string{"\\", "_", "*", "[", "]", "(", ")", "~", "`", ">", "#", "+", "-", "=", "|", "{", "}", ".", "!"}
+	for _, symbol := range symbols {
+		s = strings.ReplaceAll(s, symbol, "\\"+symbol)
+	}
+	return MarkdownV2(s)
+}
+
+// Bold returns s wrapped as bold Telegram MarkdownV2 text.
+func (s MarkdownV2) Bold() MarkdownV2 {
+	return "*" + s + "*"
+}
+
+// Italic returns s wrapped as italic Telegram MarkdownV2 text.
+func (s MarkdownV2) Italic() MarkdownV2 {
+	return "_" + s + "_"
+}
+
+// Underline returns s wrapped as underlined Telegram MarkdownV2 text.
+func (s MarkdownV2) Underline() MarkdownV2 {
+	return "__" + s + "__"
+}
+
+// Strikethrough returns s wrapped as strikethrough Telegram MarkdownV2 text.
+func (s MarkdownV2) Strikethrough() MarkdownV2 {
+	return "~" + s + "~"
+}
+
+// Spoiler returns s wrapped as spoiler Telegram MarkdownV2 text.
+func (s MarkdownV2) Spoiler() MarkdownV2 {
+	return "||" + s + "||"
+}
+
+// Link returns s as a Telegram MarkdownV2 text link.
+func (s MarkdownV2) Link(url string) MarkdownV2 {
+	return "[" + s + "](" + escapeMarkdownV2LinkDestination(url) + ")"
+}
+
+// Mention returns s as a Telegram MarkdownV2 user mention.
+func (s MarkdownV2) Mention(userID uint64) MarkdownV2 {
+	return "[" + s + "](tg://user?id=" + MarkdownV2(strconv.FormatUint(userID, 10)) + ")"
+}
+
+// Emoji returns s as a Telegram MarkdownV2 custom emoji.
+func (s MarkdownV2) Emoji(emojiID string) MarkdownV2 {
+	return "[" + s + "](tg://emoji?id=" + escapeMarkdownV2LinkDestination(emojiID) + ")"
+}
+
+// Time returns s as a Telegram MarkdownV2 localized timestamp.
+func (s MarkdownV2) Time(unix uint64) MarkdownV2 {
+	return "![" + s + "](tg://time?unix=" + MarkdownV2(strconv.FormatUint(unix, 10)) + ")"
+}
+
+// TimeFormat returns s as a Telegram MarkdownV2 localized timestamp with format.
+func (s MarkdownV2) TimeFormat(unix uint64, format string) MarkdownV2 {
+	dest := "tg://time?unix=" + strconv.FormatUint(unix, 10) + "&format=" + format
+	return "![" + s + "](" + escapeMarkdownV2LinkDestination(dest) + ")"
+}
+
+// InlineCode returns s wrapped as inline code Telegram MarkdownV2 text.
+func (s MarkdownV2) InlineCode() MarkdownV2 {
+	return "`" + s + "`"
+}
+
+// BlockCode returns s wrapped as a Telegram MarkdownV2 code block.
+func (s MarkdownV2) BlockCode() MarkdownV2 {
+	return "```\n" + s + "\n```"
+}
+
+// BlockCodeLanguage returns s wrapped as a Telegram MarkdownV2 code block with language.
+func (s MarkdownV2) BlockCodeLanguage(lang string) MarkdownV2 {
+	return "```" + MarkdownV2(lang) + "\n" + s + "\n```"
+}
+
+// Quote returns s as a Telegram MarkdownV2 blockquote.
+func (s MarkdownV2) Quote() MarkdownV2 {
+	return MarkdownV2(">" + strings.ReplaceAll(string(s), "\n", "\n>"))
+}
+
+// QuoteExpandable returns s as a Telegram MarkdownV2 expandable blockquote.
+func (s MarkdownV2) QuoteExpandable() MarkdownV2 {
+	return "**>" + s
+}
+
+func escapeMarkdownV2LinkDestination(s string) MarkdownV2 {
+	s = strings.ReplaceAll(s, "\\", "\\\\")
+	s = strings.ReplaceAll(s, ")", "\\)")
+	return MarkdownV2(s)
+}

tgfmt/mdv2_test.go

@@ -0,0 +1,78 @@
+package tgfmt
+
+import "testing"
+
+func TestEscapeMarkdownV2(t *testing.T) {
+	got := EscapeMarkdownV2(`a_b*c[1](x)!`)
+	want := MarkdownV2(`a\_b\*c\[1\]\(x\)\!`)
+
+	if got != want {
+		t.Fatalf("EscapeMarkdownV2() = %q, want %q", got, want)
+	}
+}
+
+func TestMarkdownV2ComposesWithoutDoubleEscaping(t *testing.T) {
+	got := EscapeMarkdownV2("a*b").Bold().Italic()
+	want := MarkdownV2(`_*a\*b*_`)
+
+	if got != want {
+		t.Fatalf("formatted text = %q, want %q", got, want)
+	}
+}
+
+func TestMarkdownV2FormattingMethods(t *testing.T) {
+	tests := []struct {
+		name string
+		got  MarkdownV2
+		want MarkdownV2
+	}{
+		{name: "bold", got: EscapeMarkdownV2("text").Bold(), want: "*text*"},
+		{name: "italic", got: EscapeMarkdownV2("text").Italic(), want: "_text_"},
+		{name: "underline", got: EscapeMarkdownV2("text").Underline(), want: "__text__"},
+		{name: "strikethrough", got: EscapeMarkdownV2("text").Strikethrough(), want: "~text~"},
+		{name: "spoiler", got: EscapeMarkdownV2("text").Spoiler(), want: "||text||"},
+		{name: "inline code", got: EscapeMarkdownV2("text").InlineCode(), want: "`text`"},
+		{name: "block code", got: EscapeMarkdownV2("text").BlockCode(), want: "```\ntext\n```"},
+		{name: "block code language", got: EscapeMarkdownV2("text").BlockCodeLanguage("go"), want: "```go\ntext\n```"},
+		{name: "quote", got: EscapeMarkdownV2("a\nb").Quote(), want: ">a\n>b"},
+		{name: "expandable quote", got: EscapeMarkdownV2("text").QuoteExpandable(), want: "**>text"},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			if tt.got != tt.want {
+				t.Fatalf("formatted text = %q, want %q", tt.got, tt.want)
+			}
+		})
+	}
+}
+
+func TestMarkdownV2LinkEscapesDestination(t *testing.T) {
+	got := EscapeMarkdownV2("Laniakea").Link(`https://example.test/a)b\c`)
+	want := MarkdownV2(`[Laniakea](https://example.test/a\)b\\c)`)
+
+	if got != want {
+		t.Fatalf("Link() = %q, want %q", got, want)
+	}
+}
+
+func TestMarkdownV2SpecialLinks(t *testing.T) {
+	tests := []struct {
+		name string
+		got  MarkdownV2
+		want MarkdownV2
+	}{
+		{name: "mention", got: EscapeMarkdownV2("User").Mention(123), want: "[User](tg://user?id=123)"},
+		{name: "emoji", got: EscapeMarkdownV2("emoji").Emoji(`12)3`), want: `[emoji](tg://emoji?id=12\)3)`},
+		{name: "time", got: EscapeMarkdownV2("date").Time(1772323200), want: "![date](tg://time?unix=1772323200)"},
+		{name: "time format", got: EscapeMarkdownV2("date").TimeFormat(1772323200, `MMM ) yyyy`), want: `![date](tg://time?unix=1772323200&format=MMM \) yyyy)`},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			if tt.got != tt.want {
+				t.Fatalf("formatted link = %q, want %q", tt.got, tt.want)
+			}
+		})
+	}
+}

tgfmt/message_builder.go

@@ -0,0 +1,333 @@
+package tgfmt
+
+import (
+	"strings"
+	"time"
+
+	"git.scuroneko.dev/scuroneko/extypes"
+	"git.scuroneko.dev/scuroneko/laniakea/tgapi"
+)
+
+// MessageBuilder builds Telegram message text with explicit message entities.
+// MessageBuilder is not safe for concurrent use.
+type MessageBuilder struct {
+	str      string
+	offset   int
+	entities extypes.Slice[tgapi.MessageEntity]
+
+	entries extypes.Slice[*MessageBuilderEntry]
+	isDirty bool
+}
+
+// NewMessageBuilder returns an empty MessageBuilder.
+func NewMessageBuilder() *MessageBuilder {
+	return &MessageBuilder{
+		entities: make([]tgapi.MessageEntity, 0),
+		entries:  make(extypes.Slice[*MessageBuilderEntry], 0),
+		isDirty:  false,
+	}
+}
+
+// String returns the built message text.
+func (b *MessageBuilder) String() string {
+	if b.isDirty {
+		b.update()
+	}
+	return b.str
+}
+
+// Entities returns a copy of the built message entities.
+func (b *MessageBuilder) Entities() []tgapi.MessageEntity {
+	if b.isDirty {
+		b.update()
+	}
+	return append([]tgapi.MessageEntity(nil), b.entities...)
+}
+
+// Build returns the built message text and a copy of its entities.
+func (b *MessageBuilder) Build() (string, []tgapi.MessageEntity) {
+	if b.isDirty {
+		b.update()
+	}
+	return b.str, append([]tgapi.MessageEntity(nil), b.entities...)
+}
+
+// Reset clears the builder and keeps it ready for reuse.
+func (b *MessageBuilder) Reset() {
+	b.str = ""
+	b.offset = 0
+	b.entities = b.entities[:0]
+	b.entries = b.entries[:0]
+	b.isDirty = false
+}
+
+func (b *MessageBuilder) update() *MessageBuilder {
+	b.offset = 0
+
+	var textLen int
+	var entitiesLen int
+	for _, e := range b.entries {
+		textLen += len(e.text)
+		entitiesLen += len(e.entities)
+	}
+
+	b.entities = make(extypes.Slice[tgapi.MessageEntity], 0, entitiesLen)
+
+	var sb strings.Builder
+	sb.Grow(textLen)
+
+	for _, e := range b.entries {
+		sb.WriteString(e.text)
+
+		for _, entity := range e.entities {
+			entity.Offset += b.offset
+			b.entities = append(b.entities, entity)
+		}
+
+		b.offset += e.length
+	}
+
+	b.str = sb.String()
+	b.isDirty = false
+	return b
+}
+
+func (b *MessageBuilder) markDirty() {
+	b.isDirty = true
+}
+
+// MessageBuilderEntry represents text appended to a MessageBuilder.
+type MessageBuilderEntry struct {
+	text   string
+	length int
+
+	b        *MessageBuilder
+	entities extypes.Slice[tgapi.MessageEntity]
+}
+
+// Add appends plain text to the message and returns its entry for formatting.
+func (b *MessageBuilder) Add(text string) *MessageBuilderEntry {
+	e := &MessageBuilderEntry{
+		b:        b,
+		entities: make(extypes.Slice[tgapi.MessageEntity], 0),
+
+		text:   text,
+		length: telegramTextLen(text),
+	}
+	b.entries = b.entries.Push(e)
+	b.markDirty()
+
+	return e
+}
+
+// Mention marks the entry as a Telegram mention.
+func (e *MessageBuilderEntry) Mention() *MessageBuilderEntry {
+	e.addEntity(tgapi.MessageEntity{
+		Type:   tgapi.MessageEntityMention,
+		Offset: 0, Length: e.length,
+	})
+	return e
+}
+
+// Hashtag marks the entry as a Telegram hashtag.
+func (e *MessageBuilderEntry) Hashtag() *MessageBuilderEntry {
+	e.addEntity(tgapi.MessageEntity{
+		Type:   tgapi.MessageEntityHashtag,
+		Offset: 0, Length: e.length,
+	})
+	return e
+}
+
+// Cashtag marks the entry as a Telegram cashtag.
+func (e *MessageBuilderEntry) Cashtag() *MessageBuilderEntry {
+	e.addEntity(tgapi.MessageEntity{
+		Type:   tgapi.MessageEntityCashtag,
+		Offset: 0, Length: e.length,
+	})
+	return e
+}
+
+// BotCommand marks the entry as a Telegram bot command.
+func (e *MessageBuilderEntry) BotCommand() *MessageBuilderEntry {
+	e.addEntity(tgapi.MessageEntity{
+		Type:   tgapi.MessageEntityBotCommand,
+		Offset: 0, Length: e.length,
+	})
+	return e
+}
+
+// Email marks the entry as an email address.
+func (e *MessageBuilderEntry) Email() *MessageBuilderEntry {
+	e.addEntity(tgapi.MessageEntity{
+		Type:   tgapi.MessageEntityEmail,
+		Offset: 0, Length: e.length,
+	})
+	return e
+}
+
+// Phone marks the entry as a phone number.
+func (e *MessageBuilderEntry) Phone() *MessageBuilderEntry {
+	e.addEntity(tgapi.MessageEntity{
+		Type:   tgapi.MessageEntityPhoneNumber,
+		Offset: 0, Length: e.length,
+	})
+	return e
+}
+
+// Bold marks the entry as bold text.
+func (e *MessageBuilderEntry) Bold() *MessageBuilderEntry {
+	e.addEntity(tgapi.MessageEntity{
+		Type:   tgapi.MessageEntityBold,
+		Offset: 0, Length: e.length,
+	})
+	return e
+}
+
+// Italic marks the entry as italic text.
+func (e *MessageBuilderEntry) Italic() *MessageBuilderEntry {
+	e.addEntity(tgapi.MessageEntity{
+		Type:   tgapi.MessageEntityItalic,
+		Offset: 0, Length: e.length,
+	})
+	return e
+}
+
+// Underline marks the entry as underlined text.
+func (e *MessageBuilderEntry) Underline() *MessageBuilderEntry {
+	e.addEntity(tgapi.MessageEntity{
+		Type:   tgapi.MessageEntityUnderline,
+		Offset: 0, Length: e.length,
+	})
+	return e
+}
+
+// Strikethrough marks the entry as strikethrough text.
+func (e *MessageBuilderEntry) Strikethrough() *MessageBuilderEntry {
+	e.addEntity(tgapi.MessageEntity{
+		Type:   tgapi.MessageEntityStrike,
+		Offset: 0, Length: e.length,
+	})
+	return e
+}
+
+// Spoiler marks the entry as spoiler text.
+func (e *MessageBuilderEntry) Spoiler() *MessageBuilderEntry {
+	e.addEntity(tgapi.MessageEntity{
+		Type:   tgapi.MessageEntitySpoiler,
+		Offset: 0, Length: e.length,
+	})
+	return e
+}
+
+// Quote marks the entry as a blockquote.
+func (e *MessageBuilderEntry) Quote() *MessageBuilderEntry {
+	e.addEntity(tgapi.MessageEntity{
+		Type:   tgapi.MessageEntityBlockquote,
+		Offset: 0, Length: e.length,
+	})
+	return e
+}
+
+// ExpandableQuote marks the entry as an expandable blockquote.
+func (e *MessageBuilderEntry) ExpandableQuote() *MessageBuilderEntry {
+	e.addEntity(tgapi.MessageEntity{
+		Type:   tgapi.MessageEntityExpandableBlockquote,
+		Offset: 0, Length: e.length,
+	})
+	return e
+}
+
+// InlineCode marks the entry as inline code.
+func (e *MessageBuilderEntry) InlineCode() *MessageBuilderEntry {
+	e.addEntity(tgapi.MessageEntity{
+		Type:   tgapi.MessageEntityCode,
+		Offset: 0, Length: e.length,
+	})
+	return e
+}
+
+// CodeBlock marks the entry as a preformatted code block.
+func (e *MessageBuilderEntry) CodeBlock() *MessageBuilderEntry {
+	e.addEntity(tgapi.MessageEntity{
+		Type:   tgapi.MessageEntityPre,
+		Offset: 0, Length: e.length,
+	})
+	return e
+}
+
+// CodeBlockWithLanguage marks the entry as a preformatted code block with language.
+func (e *MessageBuilderEntry) CodeBlockWithLanguage(lang string) *MessageBuilderEntry {
+	e.addEntity(tgapi.MessageEntity{
+		Type:   tgapi.MessageEntityPre,
+		Offset: 0, Length: e.length, Language: lang,
+	})
+	return e
+}
+
+// Link marks the entry as a text link.
+func (e *MessageBuilderEntry) Link(url string) *MessageBuilderEntry {
+	e.addEntity(tgapi.MessageEntity{
+		Type:   tgapi.MessageEntityTextLink,
+		Offset: 0, Length: e.length, URL: url,
+	})
+	return e
+}
+
+// TextMention marks the entry as a mention of user.
+func (e *MessageBuilderEntry) TextMention(user *tgapi.User) *MessageBuilderEntry {
+	e.addEntity(tgapi.MessageEntity{
+		Type:   tgapi.MessageEntityTextMention,
+		Offset: 0, Length: e.length, User: user,
+	})
+	return e
+}
+
+// CustomEmoji marks the entry as a custom emoji.
+func (e *MessageBuilderEntry) CustomEmoji(emojiID string) *MessageBuilderEntry {
+	e.addEntity(tgapi.MessageEntity{
+		Type:   tgapi.MessageEntityCustomEmoji,
+		Offset: 0, Length: e.length, CustomEmojiID: emojiID,
+	})
+	return e
+}
+
+// DateTime marks the entry as a localized timestamp.
+func (e *MessageBuilderEntry) DateTime(time time.Time) *MessageBuilderEntry {
+	e.addEntity(tgapi.MessageEntity{
+		Type:   tgapi.MessageEntityDateTime,
+		Offset: 0, Length: e.length, UnixTime: time.Unix(),
+	})
+	return e
+}
+
+// DateTimeFormat marks the entry as a localized timestamp with format.
+func (e *MessageBuilderEntry) DateTimeFormat(time time.Time, format string) *MessageBuilderEntry {
+	e.addEntity(tgapi.MessageEntity{
+		Type:   tgapi.MessageEntityDateTime,
+		Offset: 0, Length: e.length,
+		UnixTime: time.Unix(), DateTimeFormat: format,
+	})
+	return e
+}
+
+func telegramTextLen(text string) int {
+	n := 0
+	for _, r := range text {
+		if r <= 0xFFFF {
+			n++
+		} else {
+			n += 2
+		}
+	}
+	return n
+}
+
+func (e *MessageBuilderEntry) addEntity(entity tgapi.MessageEntity) {
+	if entity.Length <= 0 {
+		return
+	}
+	e.entities = append(e.entities, entity)
+	if e.b != nil {
+		e.b.markDirty()
+	}
+}

tgfmt/message_builder_test.go

@@ -0,0 +1,416 @@
+package tgfmt
+
+import (
+	"reflect"
+	"testing"
+	"time"
+
+	"git.scuroneko.dev/scuroneko/laniakea/tgapi"
+)
+
+func TestMessageBuilder_BuildPlainText(t *testing.T) {
+	b := NewMessageBuilder()
+
+	b.Add("Hello")
+	b.Add(", ")
+	b.Add("world")
+
+	text, entities := b.Build()
+
+	if text != "Hello, world" {
+		t.Fatalf("text = %q, want %q", text, "Hello, world")
+	}
+
+	if len(entities) != 0 {
+		t.Fatalf("entities len = %d, want 0", len(entities))
+	}
+}
+
+func TestMessageBuilder_EntityOffsetsAreUTF16(t *testing.T) {
+	b := NewMessageBuilder()
+
+	b.Add("Hi ")
+	b.Add("👋") // 2 UTF-16 code units
+	b.Add(" ")
+	b.Add("world").Bold()
+
+	text, entities := b.Build()
+
+	if text != "Hi 👋 world" {
+		t.Fatalf("text = %q, want %q", text, "Hi 👋 world")
+	}
+
+	want := []tgapi.MessageEntity{
+		{
+			Type:   tgapi.MessageEntityBold,
+			Offset: 6, // H i space = 3, 👋 = 2, space = 1
+			Length: 5,
+		},
+	}
+
+	if !reflect.DeepEqual(entities, want) {
+		t.Fatalf("entities = %#v, want %#v", entities, want)
+	}
+}
+
+func TestMessageBuilder_EntityLengthIsUTF16(t *testing.T) {
+	b := NewMessageBuilder()
+
+	b.Add("👋").Bold()
+
+	text, entities := b.Build()
+
+	if text != "👋" {
+		t.Fatalf("text = %q, want %q", text, "👋")
+	}
+
+	want := []tgapi.MessageEntity{
+		{
+			Type:   tgapi.MessageEntityBold,
+			Offset: 0,
+			Length: 2,
+		},
+	}
+
+	if !reflect.DeepEqual(entities, want) {
+		t.Fatalf("entities = %#v, want %#v", entities, want)
+	}
+}
+
+func TestMessageBuilder_MultipleEntitiesOnSameEntry(t *testing.T) {
+	b := NewMessageBuilder()
+
+	b.Add("hello").Bold().Italic()
+
+	_, entities := b.Build()
+
+	want := []tgapi.MessageEntity{
+		{
+			Type:   tgapi.MessageEntityBold,
+			Offset: 0,
+			Length: 5,
+		},
+		{
+			Type:   tgapi.MessageEntityItalic,
+			Offset: 0,
+			Length: 5,
+		},
+	}
+
+	if !reflect.DeepEqual(entities, want) {
+		t.Fatalf("entities = %#v, want %#v", entities, want)
+	}
+}
+
+func TestMessageBuilder_DoesNotDuplicateAfterRepeatedReads(t *testing.T) {
+	b := NewMessageBuilder()
+
+	b.Add("hello").Bold()
+
+	text1 := b.String()
+	entities1 := b.Entities()
+
+	text2 := b.String()
+	entities2 := b.Entities()
+
+	if text1 != text2 {
+		t.Fatalf("texts differ: %q != %q", text1, text2)
+	}
+
+	if !reflect.DeepEqual(entities1, entities2) {
+		t.Fatalf("entities differ: %#v != %#v", entities1, entities2)
+	}
+
+	want := []tgapi.MessageEntity{
+		{
+			Type:   tgapi.MessageEntityBold,
+			Offset: 0,
+			Length: 5,
+		},
+	}
+
+	if !reflect.DeepEqual(entities2, want) {
+		t.Fatalf("entities = %#v, want %#v", entities2, want)
+	}
+}
+
+func TestMessageBuilder_AddEntityAfterStringMarksDirty(t *testing.T) {
+	b := NewMessageBuilder()
+
+	entry := b.Add("hello")
+
+	if got := b.String(); got != "hello" {
+		t.Fatalf("String() = %q, want %q", got, "hello")
+	}
+
+	entry.Bold()
+
+	entities := b.Entities()
+
+	want := []tgapi.MessageEntity{
+		{
+			Type:   tgapi.MessageEntityBold,
+			Offset: 0,
+			Length: 5,
+		},
+	}
+
+	if !reflect.DeepEqual(entities, want) {
+		t.Fatalf("entities = %#v, want %#v", entities, want)
+	}
+}
+
+func TestMessageBuilder_EntitiesReturnsCopy(t *testing.T) {
+	b := NewMessageBuilder()
+
+	b.Add("hello").Bold()
+
+	entities1 := b.Entities()
+	entities1[0].Offset = 999
+
+	entities2 := b.Entities()
+
+	if entities2[0].Offset != 0 {
+		t.Fatalf("Entities() did not return copy: offset = %d, want 0", entities2[0].Offset)
+	}
+}
+
+func TestMessageBuilder_BuildReturnsEntitiesCopy(t *testing.T) {
+	b := NewMessageBuilder()
+
+	b.Add("hello").Bold()
+
+	_, entities1 := b.Build()
+	entities1[0].Offset = 999
+
+	_, entities2 := b.Build()
+
+	if entities2[0].Offset != 0 {
+		t.Fatalf("Build() did not return entities copy: offset = %d, want 0", entities2[0].Offset)
+	}
+}
+
+func TestMessageBuilder_Reset(t *testing.T) {
+	b := NewMessageBuilder()
+
+	b.Add("hello").Bold()
+
+	if got := b.String(); got != "hello" {
+		t.Fatalf("String() before Reset = %q, want %q", got, "hello")
+	}
+
+	b.Reset()
+
+	text, entities := b.Build()
+
+	if text != "" {
+		t.Fatalf("text after Reset = %q, want empty", text)
+	}
+
+	if len(entities) != 0 {
+		t.Fatalf("entities len after Reset = %d, want 0", len(entities))
+	}
+
+	b.Add("world").Italic()
+
+	text, entities = b.Build()
+
+	if text != "world" {
+		t.Fatalf("text after reuse = %q, want %q", text, "world")
+	}
+
+	want := []tgapi.MessageEntity{
+		{
+			Type:   tgapi.MessageEntityItalic,
+			Offset: 0,
+			Length: 5,
+		},
+	}
+
+	if !reflect.DeepEqual(entities, want) {
+		t.Fatalf("entities after reuse = %#v, want %#v", entities, want)
+	}
+}
+
+func TestMessageBuilder_EmptyEntryDoesNotCreateEntity(t *testing.T) {
+	b := NewMessageBuilder()
+
+	b.Add("").Bold()
+	b.Add("x")
+
+	text, entities := b.Build()
+
+	if text != "x" {
+		t.Fatalf("text = %q, want %q", text, "x")
+	}
+
+	if len(entities) != 0 {
+		t.Fatalf("entities len = %d, want 0: %#v", len(entities), entities)
+	}
+}
+
+func TestMessageBuilder_Link(t *testing.T) {
+	b := NewMessageBuilder()
+
+	b.Add("OpenAI").Link("https://openai.com")
+
+	_, entities := b.Build()
+
+	want := []tgapi.MessageEntity{
+		{
+			Type:   tgapi.MessageEntityTextLink,
+			Offset: 0,
+			Length: 6,
+			URL:    "https://openai.com",
+		},
+	}
+
+	if !reflect.DeepEqual(entities, want) {
+		t.Fatalf("entities = %#v, want %#v", entities, want)
+	}
+}
+
+func TestMessageBuilder_CodeBlockWithLanguage(t *testing.T) {
+	b := NewMessageBuilder()
+
+	b.Add("fmt.Println(\"hi\")").CodeBlockWithLanguage("go")
+
+	_, entities := b.Build()
+
+	want := []tgapi.MessageEntity{
+		{
+			Type:     tgapi.MessageEntityPre,
+			Offset:   0,
+			Length:   17,
+			Language: "go",
+		},
+	}
+
+	if !reflect.DeepEqual(entities, want) {
+		t.Fatalf("entities = %#v, want %#v", entities, want)
+	}
+}
+
+func TestMessageBuilder_DateTimeFormat(t *testing.T) {
+	b := NewMessageBuilder()
+
+	ts := time.Unix(1772323200, 0)
+
+	b.Add("date").DateTimeFormat(ts, "MMMM d, yyyy")
+
+	_, entities := b.Build()
+
+	want := []tgapi.MessageEntity{
+		{
+			Type:           tgapi.MessageEntityDateTime,
+			Offset:         0,
+			Length:         4,
+			UnixTime:       1772323200,
+			DateTimeFormat: "MMMM d, yyyy",
+		},
+	}
+
+	if !reflect.DeepEqual(entities, want) {
+		t.Fatalf("entities = %#v, want %#v", entities, want)
+	}
+}
+
+func TestTelegramTextLen(t *testing.T) {
+	tests := []struct {
+		name string
+		text string
+		want int
+	}{
+		{
+			name: "ascii",
+			text: "hello",
+			want: 5,
+		},
+		{
+			name: "cyrillic",
+			text: "привет",
+			want: 6,
+		},
+		{
+			name: "emoji",
+			text: "👋",
+			want: 2,
+		},
+		{
+			name: "mixed",
+			text: "a👋b",
+			want: 4,
+		},
+		{
+			name: "zwj sequence",
+			text: "👨‍👩‍👧‍👦",
+			want: 11,
+		},
+		{
+			name: "flag",
+			text: "🇫🇮",
+			want: 4,
+		},
+		{
+			name: "variation selector",
+			text: "❤️",
+			want: 2,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got := telegramTextLen(tt.text)
+			if got != tt.want {
+				t.Fatalf("telegramTextLen(%q) = %d, want %d", tt.text, got, tt.want)
+			}
+		})
+	}
+}
+
+func TestMessageBuilder_SimpleEntityTypes(t *testing.T) {
+	tests := []struct {
+		name string
+		add  func(*MessageBuilderEntry)
+		want tgapi.MessageEntityType
+	}{
+		{"mention", func(e *MessageBuilderEntry) { e.Mention() }, tgapi.MessageEntityMention},
+		{"hashtag", func(e *MessageBuilderEntry) { e.Hashtag() }, tgapi.MessageEntityHashtag},
+		{"cashtag", func(e *MessageBuilderEntry) { e.Cashtag() }, tgapi.MessageEntityCashtag},
+		{"bot command", func(e *MessageBuilderEntry) { e.BotCommand() }, tgapi.MessageEntityBotCommand},
+		{"email", func(e *MessageBuilderEntry) { e.Email() }, tgapi.MessageEntityEmail},
+		{"phone", func(e *MessageBuilderEntry) { e.Phone() }, tgapi.MessageEntityPhoneNumber},
+		{"bold", func(e *MessageBuilderEntry) { e.Bold() }, tgapi.MessageEntityBold},
+		{"italic", func(e *MessageBuilderEntry) { e.Italic() }, tgapi.MessageEntityItalic},
+		{"underline", func(e *MessageBuilderEntry) { e.Underline() }, tgapi.MessageEntityUnderline},
+		{"strikethrough", func(e *MessageBuilderEntry) { e.Strikethrough() }, tgapi.MessageEntityStrike},
+		{"spoiler", func(e *MessageBuilderEntry) { e.Spoiler() }, tgapi.MessageEntitySpoiler},
+		{"quote", func(e *MessageBuilderEntry) { e.Quote() }, tgapi.MessageEntityBlockquote},
+		{"expandable quote", func(e *MessageBuilderEntry) { e.ExpandableQuote() }, tgapi.MessageEntityExpandableBlockquote},
+		{"inline code", func(e *MessageBuilderEntry) { e.InlineCode() }, tgapi.MessageEntityCode},
+		{"code block", func(e *MessageBuilderEntry) { e.CodeBlock() }, tgapi.MessageEntityPre},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			b := NewMessageBuilder()
+
+			e := b.Add("hello")
+			tt.add(e)
+
+			_, entities := b.Build()
+
+			want := []tgapi.MessageEntity{
+				{
+					Type:   tt.want,
+					Offset: 0,
+					Length: 5,
+				},
+			}
+
+			if !reflect.DeepEqual(entities, want) {
+				t.Fatalf("entities = %#v, want %#v", entities, want)
+			}
+		})
+	}
+}

tgfmt/utils.go

@@ -0,0 +1,12 @@
+package tgfmt
+
+import "strings"
+
+// EscapePunctuation escapes '.', '!' and '-' for MarkdownV2 fragments.
+func EscapePunctuation(s string) string {
+	symbols := []string{".", "!", "-"}
+	for _, symbol := range symbols {
+		s = strings.ReplaceAll(s, symbol, "\\"+symbol)
+	}
+	return s
+}

update_context.go

@@ -0,0 +1,223 @@
+package laniakea
+
+import (
+	"time"
+
+	"git.scuroneko.dev/scuroneko/laniakea/tgapi"
+)
+
+func (bot *Bot[T]) handleUpdate(u *tgapi.Update, ctx *MessageContext) bool {
+	handled := false
+	for _, plugin := range bot.plugins {
+		handler, ok := plugin.handlers[u.Type]
+		if !ok {
+			continue
+		}
+
+		pluginCtx := cloneMsgContext(ctx)
+		if plugin.logger != nil {
+			pluginCtx.Logger = plugin.logger
+		}
+		if !plugin.executeMiddlewares(pluginCtx, bot.appData) {
+			continue
+		}
+		startTime := time.Now()
+		bot.safeEmitEvent(pluginCtx.Context(), HandlerStartedEvent{
+			UpdateID:    u.UpdateID,
+			UpdateType:  u.Type,
+			Plugin:      plugin.name,
+			HandlerKind: HandlerUpdateKind,
+			HandlerName: string(u.Type),
+			FromID:      pluginCtx.FromID,
+			ChatID:      pluginCtx.ChatID,
+		})
+		err := handler(pluginCtx, bot.appData)
+		endEvent := HandlerFinishedEvent{
+			UpdateID:    u.UpdateID,
+			UpdateType:  u.Type,
+			Plugin:      plugin.name,
+			HandlerKind: HandlerUpdateKind,
+			HandlerName: string(u.Type),
+			FromID:      pluginCtx.FromID,
+			ChatID:      pluginCtx.ChatID,
+			Duration:    time.Since(startTime),
+		}
+		if err != nil {
+			endEvent.Err = err
+			endEvent.UserFacing = IsUserError(err)
+		}
+		bot.safeEmitEvent(pluginCtx.Context(), endEvent)
+		if err != nil {
+			bot.safeEmitEvent(pluginCtx.Context(), ErrorEvent{
+				UpdateID:    u.UpdateID,
+				UpdateType:  u.Type,
+				Plugin:      plugin.name,
+				HandlerKind: HandlerUpdateKind,
+				HandlerName: string(u.Type),
+				FromID:      pluginCtx.FromID,
+				ChatID:      pluginCtx.ChatID,
+				Err:         err,
+				UserFacing:  IsUserError(err),
+			})
+			pluginCtx.error(err)
+		}
+		handled = true
+	}
+	return handled
+}
+
+func (bot *Bot[T]) prepareUpdateCtx(u *tgapi.Update, ctx *MessageContext) {
+	var from *tgapi.User
+	var chat *tgapi.Chat
+	switch u.Type {
+	case tgapi.UpdateTypeMessage:
+		if u.Message != nil {
+			ctx.Msg = u.Message
+			if u.Message.Chat != nil {
+				chat = u.Message.Chat
+			}
+			if u.Message.From != nil {
+				from = u.Message.From
+			}
+		}
+	case tgapi.UpdateTypeEditedMessage:
+		if u.EditedMessage != nil {
+			ctx.Msg = u.EditedMessage
+			if u.EditedMessage.Chat != nil {
+				chat = u.EditedMessage.Chat
+			}
+			if u.EditedMessage.From != nil {
+				from = u.EditedMessage.From
+			}
+		}
+	case tgapi.UpdateTypeChannelPost:
+		if u.ChannelPost != nil {
+			ctx.Msg = u.ChannelPost
+			if u.ChannelPost.Chat != nil {
+				chat = u.ChannelPost.Chat
+			}
+			if u.ChannelPost.From != nil {
+				from = u.ChannelPost.From
+			}
+		}
+	case tgapi.UpdateTypeEditedChannelPost:
+		if u.EditedChannelPost != nil {
+			ctx.Msg = u.EditedChannelPost
+			if u.EditedChannelPost.Chat != nil {
+				chat = u.EditedChannelPost.Chat
+			}
+			if u.EditedChannelPost.From != nil {
+				from = u.EditedChannelPost.From
+			}
+		}
+	case tgapi.UpdateTypeBusinessMessage:
+		if u.BusinessMessage != nil {
+			ctx.Msg = u.BusinessMessage
+			if u.BusinessMessage.Chat != nil {
+				chat = u.BusinessMessage.Chat
+			}
+			if u.BusinessMessage.From != nil {
+				from = u.BusinessMessage.From
+			}
+		}
+	case tgapi.UpdateTypeEditedBusinessMessage:
+		if u.EditedBusinessMessage != nil {
+			ctx.Msg = u.EditedBusinessMessage
+			if u.EditedBusinessMessage.Chat != nil {
+				chat = u.EditedBusinessMessage.Chat
+			}
+			if u.EditedBusinessMessage.From != nil {
+				from = u.EditedBusinessMessage.From
+			}
+		}
+	case tgapi.UpdateTypeInlineQuery:
+		if u.InlineQuery != nil {
+			from = &u.InlineQuery.From
+		}
+	case tgapi.UpdateTypeChosenInlineResult:
+		if u.ChosenInlineResult != nil {
+			from = &u.ChosenInlineResult.From
+		}
+	case tgapi.UpdateTypeCallbackQuery:
+		if u.CallbackQuery != nil {
+			if u.CallbackQuery.Message != nil {
+				ctx.Msg = u.CallbackQuery.Message
+				ctx.CallbackMsgID = u.CallbackQuery.Message.MessageID
+				if u.CallbackQuery.Message.Chat != nil {
+					chat = u.CallbackQuery.Message.Chat
+				}
+			}
+			if u.CallbackQuery.InlineMessageID != nil {
+				ctx.InlineMsgID = *u.CallbackQuery.InlineMessageID
+			}
+			ctx.CallbackQueryID = u.CallbackQuery.ID
+			from = &u.CallbackQuery.From
+		}
+	case tgapi.UpdateTypeShippingQuery:
+		if u.ShippingQuery != nil {
+			from = &u.ShippingQuery.From
+		}
+	case tgapi.UpdateTypePreCheckoutQuery:
+		if u.PreCheckoutQuery != nil {
+			from = &u.PreCheckoutQuery.From
+		}
+	case tgapi.UpdateTypePurchasedPaidMedia:
+		if u.PurchasedPaidMedia != nil {
+			from = &u.PurchasedPaidMedia.From
+		}
+	case tgapi.UpdateTypeMyChatMember:
+		if u.MyChatMember != nil {
+			from = &u.MyChatMember.From
+			chat = &u.MyChatMember.Chat
+		}
+	case tgapi.UpdateTypeChatMember:
+		if u.ChatMember != nil {
+			from = &u.ChatMember.From
+			chat = &u.ChatMember.Chat
+		}
+	case tgapi.UpdateTypeChatJoinRequest:
+		if u.ChatJoinRequest != nil {
+			from = &u.ChatJoinRequest.From
+			chat = &u.ChatJoinRequest.Chat
+
+		}
+	case tgapi.UpdateTypeBusinessConnection:
+		if u.BusinessConnection != nil {
+			from = &u.BusinessConnection.User
+		}
+	case tgapi.UpdateTypePollAnswer:
+		if u.PollAnswer != nil {
+			from = &u.PollAnswer.User
+		}
+	case tgapi.UpdateTypeMessageReaction:
+		if u.MessageReaction != nil {
+			from = u.MessageReaction.User
+			chat = u.MessageReaction.Chat
+		}
+	case tgapi.UpdateTypeChatBoost:
+		if u.ChatBoost != nil {
+			from = &u.ChatBoost.Boost.Source.User
+			chat = &u.ChatBoost.Chat
+		}
+	case tgapi.UpdateTypeRemovedChatBoost:
+		if u.RemovedChatBoost != nil {
+			from = &u.RemovedChatBoost.Source.User
+			chat = &u.RemovedChatBoost.Chat
+		}
+	}
+	if ctx.Msg != nil && from == nil {
+		from = ctx.Msg.From
+	}
+	if from != nil {
+		ctx.From = from
+		ctx.FromID = from.ID
+	} else {
+		ctx.FromID = 0
+	}
+	if chat != nil {
+		ctx.Chat = chat
+		ctx.ChatID = chat.ID
+	} else {
+		ctx.ChatID = 0
+	}
+}