(new): rich message support

(fix): runtime reliability
(tests): regression coverage
(doc): v1.1 release notes

.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,9 @@
 .idea/
-test/
+.wiki/
+.vscode/
+test/
+.codex/
+.codex
+.agents/
+.claude/
+review.md

.golangci.yml

@@ -0,0 +1,13 @@
+version: "2"
+run:
+  timeout: 5m
+linters:
+  default: none
+  enable:
+    - errcheck
+    - ineffassign
+    - staticcheck
+    - unused
+issues:
+  max-issues-per-linter: 0
+  max-same-issues: 0

.pre-commit-config.yaml

@@ -0,0 +1,41 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v6.0.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-merge-conflict
+      - id: check-yaml
+      - id: check-json
+      - id: mixed-line-ending
+        args: ["--fix=lf"]
+
+  - repo: local
+    hooks:
+      - id: gofmt
+        name: gofmt
+        entry: gofmt -w
+        language: system
+        types: [go]
+
+      - id: go-vet
+        name: go vet
+        entry: go vet ./...
+        language: system
+        pass_filenames: false
+        types: [go]
+
+      - id: golangci-lint
+        name: golangci-lint
+        entry: golangci-lint run
+        language: system
+        pass_filenames: false
+        types: [go]
+
+      - id: go-test
+        name: go test
+        entry: go test ./...
+        language: system
+        pass_filenames: false
+        stages: [pre-push]
+        types: [go]

AGENTS.md

@@ -0,0 +1,173 @@
+# AGENTS.md
+
+## Purpose
+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.
+
+## Review priorities
+Review the codebase with focus on:
+- correctness and reliability;
+- maintainability and architecture;
+- idiomatic Go;
+- testability;
+- performance where justified by code evidence;
+- security;
+- godoc quality.
+
+## Scope rules
+- Always review the whole repository unless the prompt explicitly narrows scope.
+- Check cross-package interactions, public APIs, package boundaries, and shared patterns.
+- Prefer concrete fixes over generic advice.
+- 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;
+- poor error handling;
+- misuse of context, cancellation, timeouts, retries, and cleanup;
+- race risks, deadlocks, blocking hazards, unsafe shared state;
+- non-idiomatic naming, APIs, interfaces, package structure, and error patterns;
+- unnecessary complexity, duplication, or weak abstractions;
+- obvious performance problems supported by the code;
+- security risks such as unsafe input handling, secret leakage, insecure logging, injection risks, and risky file or network operations.
+
+## Godoc rules
+Review comments for all declarations.
+
+### Exported declarations
+Exported types, funcs, methods, vars, and consts must have godoc comments.
+
+Each exported godoc comment must:
+- start with the identifier name;
+- explain the purpose or behavior;
+- be as short as possible without losing important meaning;
+- avoid repeating the signature mechanically;
+- stay high-signal and informative.
+
+### Telegram API documentation and versions
+- When writing or updating godoc for Telegram Bot API types, fields, methods, or helpers, verify the description against the official [Telegram Bot API documentation](https://core.telegram.org/bots/api). Preserve relevant API semantics such as HTML equivalents, accepted ranges, formats, and optionality.
+- Add a `Since: Bot API X.Y` paragraph to each exported type, function, and method introduced in a specific Bot API version, using the established `tgapi` format.
+- Add an inline `// Since: Bot API X.Y` comment to an exported struct field only when its Bot API version differs from that of the containing struct. For example, if `InputRichMessage` was introduced in Bot API 10.1 and its `Media` field in Bot API 10.2, annotate only the `Media` field; do not repeat the struct's version on its original fields.
+
+### Unexported declarations
+Unexported types, funcs, methods, vars, and consts should generally not have godoc-style comments unless there is a strong reason.
+
+### Always report
+- missing godoc on exported declarations;
+- unnecessary godoc on unexported declarations;
+- comments that are too long, vague, redundant, or low-value;
+- comments that should be shortened or rewritten.
+
+When feasible, rewrite bad godoc into better versions.
+
+## Testing expectations
+Treat tests as a required part of review.
+
+- Assess existing test quality, not only test presence.
+- Add or propose as many useful tests as reasonably possible.
+- Prioritize public APIs, critical flows, edge cases, negative paths, boundary conditions, and concurrency-sensitive logic.
+- Prefer table-driven tests where appropriate.
+- Add regression tests for bugs you find.
+- If a case is hard to test directly, explain the gap and the best test strategy.
+
+## Commands
+Before finalizing changes, run the relevant project checks when available:
+- build
+- tests
+- lint
+- static analysis
+
+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, or it's necessary(i.e. fixing not working feature).
+- If the requested change is breaking, not necessary to fix a non-working feature, 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:
+
+1. Overall summary
+2. Critical findings
+3. Major findings
+4. Minor findings
+5. Godoc issues
+6. Test gaps and added/proposed tests
+7. Good decisions worth keeping
+8. Summary of concrete changes made
+
+For each finding include:
+- location;
+- issue;
+- why it matters;
+- recommended fix.
+
+## Working style
+- Be direct, specific, and action-oriented.
+- Do not stop at style-only feedback.
+- Use full repository context before drawing conclusions.
+- Prefer minimal, high-confidence patches.
+- Preserve behavior unless intentionally fixing a bug.

CHANGELOG.md

@@ -0,0 +1,494 @@
+# Changelog
+
+## v1.1.0
+
+### Breaking Changes
+- Fixed `Uploader.SendLivePhoto` and `Uploader.SendLivePhotoWithContext` to require both the live-photo video and its static image. The previous one-file signatures could not produce a valid `sendLivePhoto` request.
+
+### Bot API 10.1
+- Added rich message receiving support: `tgapi.RichMessage` on `Message.RichMessage` (`rich_message`), the full set of `RichText*`/`RichBlock*` wire types with official API names, and `UnmarshalRichText`/`UnmarshalRichBlock`/`UnmarshalRichMessage` parsers. Unknown text-bearing types retain their nested text through fallback wrappers while unmodeled fields are discarded.
+- Added rich message sending support: `tgapi.InputRichMessage`, `tgapi.SendRichMessage` params, and `API.SendRichMessage`/`API.SendRichMessageWithContext`.
+- Added rich message draft streaming: `API.SendRichMessageDraft`/`API.SendRichMessageDraftWithContext` for ephemeral ~30-second previews of partially generated messages.
+- Added rich message editing: `EditMessageText.RichMessage` (`InputRichMessage`); `Text` is now omitted from the request when empty so rich-only edits are valid.
+- Added `tgapi.InputRichMessageContent` for rich content in inline query results.
+- Added join request query support: `User.SupportsJoinRequestQueries`, `ChatFullInfo.GuardBot`, `ChatJoinRequest.QueryID`, `API.AnswerChatJoinRequestQuery` with `ChatJoinRequestQueryResult` constants (`JoinRequestApprove`/`JoinRequestDecline`/`JoinRequestQueue`), and `API.SendChatJoinRequestWebApp` (plus `WithContext` variants).
+- Added poll link media: the `tgapi.Link` type, `PollMedia.Link`, and the "link" type with `URL` on `InputPollOptionMedia`.
+
+### Bot API 10.2
+- Added block-based rich-message sending with `InputRichMessage.Blocks`, including animation, audio, photo, video, and voice-note input blocks. The `tgrich` package provides matching media constructors with optional block captions.
+- Added `InputRichMessage.Media` for media embedded in rich-message HTML or Markdown, with multipart `attach://` upload support.
+- Added multipart rich-message uploads through `Uploader.SendRichMessage`. Use `UploaderFile.SetAttachName` to match an `attach://` media reference; rich-message draft helpers reject direct uploads as required by Telegram.
+- Added ephemeral-message support: outgoing receiver and callback parameters, reply targets, message fields, edit and delete methods, and ephemeral bot commands. Added community service-message types and subscription update handling.
+
+### Added
+- Added documented `tgrich` constructors and block types for building input rich messages.
+- Added `tgrich.BuildHTML` and `tgrich.ToHTML` to validate input block trees, convert them to HTML rich messages, and collect URL, `file_id`, or multipart media references.
+- Added `MessageContext.RichAnswer(...)` and `MessageContext.RichAnswerKeyboard(...)` for validating and sending `tgrich` input blocks.
+- Added `UpdateTypeSubscription` routing and normalized message, user, and chat context for guest messages, deleted business messages, anonymous poll answers, reaction counts, managed bots, chat boosts, and subscription updates.
+- Added webhook secret-format validation and the exported `ErrBotWebhookOptsSecretTokenInvalid` sentinel.
+
+### Changed
+- `AutoGenerateCommandsForScope(nil)` now atomically replaces commands in Telegram's default scope without deleting the previous list first.
+- API debug logging now records redacted request JSON and response metadata instead of complete response bodies.
+- Scene updates sharing a user or chat session key are serialized, and duplicate scene names from later plugins are skipped with a warning.
+- Inline keyboard button builders now keep URL and callback actions mutually exclusive, and `InlineKeyboard.Get` returns independent markup data.
+- `NewBot` no longer aliases `BotOpts.Prefixes` or mutates `BotOpts.LoggerBasePath`.
+- README requirements now match the module's Go 1.26 directive.
+- Migrated the golangci-lint configuration to its v2 schema so the repository lint workflow runs again.
+- Added missing Godoc for exported error methods, enum constants, and all public Bot API 10.1/10.2 fields introduced in this release.
+
+### Fixed
+- Fixed JSON BotOpts environment placeholders corrupting or injecting JSON when values contain quotes, backslashes, or control characters.
+- Preserved checkbox state when converting list items to ordered lists and made generated HTML attribute ordering deterministic.
+- Added validation for rich-block type discriminators, heading sizes, list fields, table cells, map parameters, and media values.
+- Fixed generated webhook secrets using padded Base64 characters that Telegram rejects, stopped logging generated secrets, and added HTTP read and idle timeouts to the webhook server.
+- Fixed negative group and channel IDs receiving global rather than per-chat `retry_after` cooldowns.
+- Fixed rejected per-chat requests consuming global rate-limit capacity and draft construction consuming an extra rate-limit token before the API request.
+- Fixed subscription updates being decoded as `UpdateTypeUnknown`.
+- Fixed rich-text and rich-block decoding silently accepting malformed typed fields or a top-level `null` rich-text value.
+- Fixed `tgrich.BuildHTML` disabling Telegram entity detection and accepting the draft-only thinking block; `BuildDraftHTML` now provides the explicit draft path.
+- Fixed `tgrich.BuildHTML` silently losing explicit bank-card, mention, hashtag, cashtag, and bot-command values when their visible text differs.
+- Fixed API debug logs exposing webhook, payment, callback, passport, and managed-bot secrets.
+- Fixed panics and nil callbacks in asynchronous middleware terminating the process; failures now reach the logger and observer error stream.
+- Fixed multipart helpers attempting direct file uploads for rich-message drafts, which Telegram does not support; they now return `ErrRichMessageDraftUploadUnsupported`.
+- Fixed draft ID zero values and collisions overwriting tracked drafts, nil draft APIs panicking, and draft entity slices aliasing caller memory.
+- Fixed scene session payloads and returned inline keyboard markup aliasing mutable internal slices.
+- Recovered panics from runner callbacks so they are reported through normal runner and error observer events instead of terminating the process.
+
+### Tests
+- Added JSON regression coverage for rich-message embedded media and ephemeral send, edit, and delete parameters.
+- Added regression coverage for escaped environment placeholders and both required `sendLivePhoto` multipart fields.
+- Added regression coverage for API log redaction, same-session scene serialization, duplicate scene registration, async middleware failures, and rich entity preservation.
+- Added rich HTML renderer coverage for all input block and media types, multipart references, field validation, and Telegram's text, block, nesting, media, and table-width limits.
+- Added regression coverage for webhook token syntax, update context normalization, subscription routing, rate-limit capacity, draft ID collisions, runner panics, scene and keyboard aliasing, command replacement, and malformed rich JSON.
+
+## 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
+- `chat_boost` update decoding now accepts string `boost_id` values, matching the current Telegram Bot API schema and preventing polling failures on boosted-chat updates.
+
+## v1.0.0-rc.10
+
+### Added
+- `Plugin.AddUpdateHandler` for routing non-command Telegram updates by `tgapi.UpdateType`.
+- Derived `tgapi.Update.Type` assignment during JSON decoding, plus `tgapi.UpdateTypeUnknown` for unmatched payloads.
+- `tgapi.API.OpenFileByLink(...)` and `OpenFileByLinkWithContext(...)` for streaming downloads from Telegram's file server.
+- Regression tests for update dispatch, keyboard builders, localization fallback, runners, rate limiting, parse mode encoding, streaming downloads, and context isolation.
+- Regression tests for bot single-run enforcement, nil plugin registration, `L10n` concurrent access, `API.Close()` idle-connection cleanup, and `tgapi` worker-pool edge cases.
+- `SEMVER.md` documenting versioning expectations for the project.
+
+### Changed
+- `NewBot` now returns `(*Bot[T], error)` instead of terminating the host process on configuration or startup failures.
+- `Run` and `RunWithContext` now return errors; `RunWithContext` returns `ErrNoPrefixes` and `ErrNoPlugins` for invalid bot configuration.
+- Polling retries now use exponential backoff instead of busy-looping on repeated `getUpdates` failures.
+- `Bot` is now explicitly single-use; repeated `Run()` or `RunWithContext(...)` calls return `ErrBotAlreadyRun`.
+- Database context wiring now uses `T` consistently instead of forcing `*T`; shared dependencies should typically use pointer types such as `*sql.DB`.
+- `DatabaseContext`, `GetDBContext`, and `DbLogger` were updated to the new `T`-based dependency model.
+- `DatabaseContext(...)` now warns once when `T` is a value type, to highlight likely unintended copying of shared dependencies.
+- `AddDatabaseLoggerWriter(...)` now skips unset and nil database contexts instead of calling the writer with invalid values.
+- `L10n` is now safe for concurrent use and copies added dictionary entries to avoid external mutation after registration.
+- Plugin registration now snapshots commands, payloads, middlewares, and update handlers so later mutations of the original `*Plugin` do not leak into the bot.
+- `AddPlugins(...)` now skips nil plugin pointers instead of panicking.
+- `GetUpdateTypes()` now returns a copy instead of exposing internal slice state.
+- Update handling now normalizes `MsgContext` for more Telegram update kinds and routes plugin-level update handlers with isolated context copies.
+- `message`, `channel_post`, and `callback_query` remain on the command/payload flow; non-command updates can be handled through plugin update handlers.
+- Command auto-generation now validates Telegram command names with the correct character set and `1..32` length limit, and emits commands in deterministic sorted order.
+- Builder-style APIs were normalized to value returns for `NewCommandArg`, `NewMiddleware`, `NewRunner`, and `NewCallbackData`.
+- `MenuButton` replaced `BaseMenuButton`, and `GetChatMenuButton(...)` now returns the renamed type.
+- Several Telegram DTOs were tightened for optionality and serialization correctness, including `InputPaidMedia`, `MenuButton`, optional gift fields, and message entity slices.
+- `tgapi.NewRequest(...)`, `NewRequestWithChatID(...)`, `NewUploaderRequest(...)`, and `NewUploaderRequestWithChatID(...)` are now documented as low-level unsafe escape hatches rather than internal helpers.
+- `tgapi.API.Close()` now closes idle HTTP connections before releasing logger resources.
+- Multipart form encoding now writes scalar field bytes directly instead of converting through temporary strings.
+- README, README_RU, package docs, and exported godoc were updated to match the current APIs and concurrency/lifecycle model.
+- Version constants were bumped to `v1.0.0-rc.10`.
+
+### Fixed
+- Required command arguments are now enforced by declared argument index, not only by total required count.
+- `ParseNone` now omits `parse_mode` from JSON requests instead of serializing `"None"`.
+- Upload file type detection is now case-insensitive for file extensions.
+- Draft creation no longer panics when no limiter is configured, and draft flushing now rejects zero chat IDs before sending invalid requests.
+- Channel posts with `SenderChat` no longer panic in the command path and now preserve the expected `MsgContext` fields.
+- File logger initialization now falls back to stdout loggers instead of terminating the process on logger setup failures.
+- `GetChatMenuButton` and `SetChatMenuButton` now serialize `chat_id` correctly when omitted.
+- Update decoding tests now match the canonical `deleted_business_messages` model and no longer rely on the removed singular alias.
+
+### Breaking Changes
+- `NewBot[T](opts)` now returns `(*Bot[T], error)`.
+- `Run()` now returns `error`.
+- `RunWithContext(ctx)` now returns `error`.
+- `Run()` and `RunWithContext(ctx)` are now single-use per bot instance; create a new `Bot` after they return.
+- Database context handlers now receive `T` instead of `*T`. For shared dependencies, instantiate the bot with a pointer type, for example `Bot[*sql.DB]`.
+- `DatabaseContext(...)` now takes `T` instead of `*T`.
+- `GetDBContext()` now returns `T` instead of `*T`.
+- `DbLogger[T]` now receives `T` instead of `*T`.
+- `NewCommandArg(...)`, `NewMiddleware(...)`, `NewRunner(...)`, and `NewCallbackData(...)` now return values instead of pointers.
+- `BaseMenuButton` was renamed to `MenuButton`, and `GetChatMenuButton(...)` now returns `MenuButton`.
+- `tgapi.Update` no longer exposes the deprecated `DeletedBusinessMessage` alias; use `DeletedBusinessMessages`.
+
+### Tests
+- Added coverage for polling backoff helpers, command sorting, database logger safety checks, update handler routing, update-context isolation, channel posts with `SenderChat`, parse mode encoding, streaming downloads, and rate limiter behavior.
+
+## v1.0.0-rc.7
+
+### Added
+- Package-level logger helpers: `utils.CreateLogger(prefix, level)` and `utils.CreateFileLogger(prefix, level, filePath)`.
+- `MsgContext.Logger`, populated from the matched plugin and falling back to the bot logger.
+- Plugin lifecycle/configuration APIs: `SetLogger`, `RemoveLogger`, `SetOnClose`, and `Close`.
+- `Bot.CloseRemote(ctx)` as the explicit wrapper for Telegram Bot API close.
+
+### Changed
+- Logger initialization is now unified across `Bot`, `tgapi.API`, and `tgapi.Uploader`.
+- `Bot.Close()` now performs local resource teardown only and invokes `Plugin.Close()` for registered plugins.
+- Local `tgapi.API` shutdown was renamed to `Close()`.
+- Telegram Bot API close wrappers in `tgapi.API` were renamed to `CloseRemote()` and `CloseRemoteWithContext()`.
+- `Bot.Debug()` now updates log levels for the bot logger, request logger, and already registered plugin loggers.
+- `Bot.AddPlugins()` now creates a default plugin logger automatically when one is not provided.
+- `Bot.AddDatabaseLoggerWriter()` now also attaches the writer to already registered plugin loggers.
+- GoDoc was expanded for the new shutdown and logging APIs, and plugin registration is now documented as a configuration commit point.
+
+### Breaking Changes
+- `(*Bot).Close(ctx context.Context)` was replaced with `(*Bot).Close()`.
+- `(*tgapi.API).CloseApi()` was renamed to `(*tgapi.API).Close()`.
+- `(*tgapi.API).Close()` was renamed to `(*tgapi.API).CloseRemote()`.
+- `(*tgapi.API).CloseWithContext()` was renamed to `(*tgapi.API).CloseRemoteWithContext(ctx)`.
+
+### Migration
+- Replace `bot.Close(ctx)` with `bot.Close()`.
+- If you need Telegram Bot API close, use `bot.CloseRemote(ctx)`.
+- Replace `api.CloseApi()` with `api.Close()`.
+- Replace `api.Close()` with `api.CloseRemote()`.
+- Replace `api.CloseWithContext(ctx)` with `api.CloseRemoteWithContext(ctx)`.
+- Configure plugin loggers and `OnClose` hooks before calling `bot.AddPlugins(...)`.
+
+### Tests
+- Updated tests for the new shutdown and logging behavior.
+
+### Notes
+- Registering a plugin via `AddPlugins(...)` is a configuration commit point; the plugin should not be mutated through the original `*Plugin` afterward.
+- If plugin loggers must receive a database writer, call `AddDatabaseLoggerWriter(...)` after registering plugins.
+
+## v1.0.0-rc.4
+
+### Added
+- `WithContext` variants across `tgapi` API and uploader methods so callers can pass cancellation and deadline contexts consistently.
+- `UploaderCertificateType`, `UploadSetWebhookP`, `Uploader.SetWebhook(...)`, and `Uploader.SetWebhookWithContext(...)` for multipart webhook certificate uploads.
+- Missing media thumbnail fields where applicable.
+
+### Changed
+- GoDoc for context-aware methods was improved, and `See` references now point to method-specific Telegram Bot API anchors.
+- `EditMessageTextP` now includes `entities` and `link_preview_options`.
+- `EditMessageCaptionP` now includes `caption_entities` and `show_caption_above_media`.
+- `StopPollP` now uses `reply_markup` and no longer carries `inline_message_id`.
+- `SendStickerP` now includes reply and suggested-post related fields.
+- `SendDocumentP` now includes `disable_content_type_detection`.
+- `SendInvoiceP` no longer includes unsupported `business_connection_id`.
+- `SetWebhookP` no longer carries `certificate`; GoDoc now points to uploader-based certificate upload.
+- Existing non-context methods remain available, and the `Do(...)` call style is preserved.
+
+### Breaking Changes
+- Users sending webhook certificates through JSON `SetWebhookP.Certificate` must migrate to `Uploader.SetWebhook(...)`.
+
+## v1.0.0-rc.3
+
+### Fixed
+- The update polling loop no longer logs or retries after `context.Canceled` during shutdown.
+- Extra retry delay was removed from canceled polling requests so `RunWithContext` can exit immediately while stopping.
+
+### Changed
+- Shutdown behavior remains explicit: callers are still responsible for invoking `Close()` after `RunWithContext` returns.
+
+## v1.0.0-rc.2
+
+### Fixed
+- Fixed a shutdown crash caused by `DatabaseWriter` calling `Close()` through an uninitialized embedded logger writer.
+- Fixed bot shutdown hanging during Telegram long polling by making update polling use a cancelable context.
+- Reduced the chance of container termination with exit code `137` during shutdown by allowing `getUpdates` to stop promptly on cancellation.
+
+### Changed
+- Switched the project to use the local `laniakea` replacement for the shutdown fix.
+- Documentation now clarifies that `RunWithContext` does not close resources automatically and callers must invoke `Close()` explicitly.
+- `Updates` documentation now describes context-driven cancellation behavior.
+
+### Tests
+- Added regression tests for database logger writer shutdown behavior.

README.md

@@ -1,3 +1,375 @@
 # Laniakea
 
-A lightweight, easy to use and performance Telegram API wrapper for bot development.
+![Laniakea](assets/logo.jpg)
+
+[![Go Version](https://img.shields.io/badge/Go-1.26+-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.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
+*   **Simple & Intuitive API:** Designed for ease of use, based on practical examples.
+*   **Plugin System:** Organize your bot's functionality into independent, reusable plugins.
+*   **Command Handling:** Easily register commands and extract arguments.
+*   **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 application data or state contexts to your handlers.
+*   **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.scuroneko.dev/scuroneko/laniakea
+```
+
+or
+
+```bash
+go get github.com/scuroneko/laniakea
+```
+
+## 🚀 Quick Start (with step-by-step explanation)
+
+Here is a minimal echo/ping bot example with detailed comments.
+```go
+package main
+
+import (
+	"log"
+
+	"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.)
+//   - data: your shared application data (here we use NoData, a placeholder for no shared data)
+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() {
+	// 1. Create bot options. Replace "TOKEN" with your actual bot token from @BotFather.
+	opts := &laniakea.BotOpts{Token: "TOKEN"}
+
+	// 2. Initialize a new bot instance.
+	//    We use laniakea.NoData as the application data type (no shared data needed for this example).
+	bot, err := laniakea.NewBot[laniakea.NoData](opts)
+	if err != nil {
+		log.Fatal(err)
+	}
+	// Ensure bot resources are cleaned up on exit.
+	defer bot.Close()
+
+	// 3. Create a new plugin named "ping".
+	//    Plugins help group related commands and middlewares.
+	p := laniakea.NewPlugin[laniakea.NoData]("ping")
+
+	// 4. Add a command to the plugin.
+	//    p.Command("echo", echo) creates a command that triggers the 'echo' function on the "/echo" command.
+	p.Command("echo", echo)
+
+	// 5. Add another command using an anonymous function (closure).
+	//    This command simply replies "Pong" when the user sends "/ping".
+	p.Command("ping", func(ctx *laniakea.MessageContext, data laniakea.NoData) error {
+		ctx.Answer("Pong")
+		return nil
+	})
+
+	// 6. Configure the bot with a custom error template and add the plugin.
+	//    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.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.
+	if err := bot.AutoGenerateCommands(); err != nil {
+		log.Println(err)
+	}
+
+	// 8. Start the bot, listening for updates (long polling).
+	if err := bot.Run(); err != nil {
+		log.Fatal(err)
+	}
+}
+```
+
+### 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 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. `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 *MessageContext (message details, methods like Answer) and your custom application data T, and return an error for centralized error handling.
+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. `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
+
+Plugins are the main way to organize code. A plugin can have multiple commands and middlewares.
+```go
+plugin := laniakea.NewPlugin[*MyDB]("admin")
+plugin.Command("ban", banUser)
+bot.AddPlugins(plugin)
+```
+
+### Commands
+
+A command is a function that handles a specific bot command (e.g., /start).
+```go
+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
+}
+```
+
+### 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.
+- `AnswerPhotoMarkdown(photoID, text string) *AnswerMessage`: Sends a photo with MarkdownV2 caption (you handle escaping).
+- `EditCallback(text string, keyboard *InlineKeyboard) *AnswerMessage`: Edits message with parse_mode none 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.
+- And more methods and fields!
+
+### tgapi: API and Uploader
+
+`tgapi` provides two clients:
+
+- `API` for JSON requests (e.g., `SendMessage`, `EditMessageText`, methods using file_id/URL).
+- `Uploader` for multipart uploads (e.g., `SendPhoto`, `SendDocument`, `SendVideo` with binary files).
+
+This split keeps method intent explicit: JSON-only calls go through `API`, file uploads go through `Uploader`.
+
+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.
+
+### App Data
+
+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 { /* ... */ }
+db := &MyDB{...}
+bot, err := laniakea.NewBot[*MyDB](opts)
+if err != nil {
+    log.Fatal(err)
+}
+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.
+
+### Signature
+A middleware function has the same signature as a command handler, but it must return a bool:
+
+```go
+func(ctx *MessageContext, db T) bool
+```
+
+- If it returns true, the next middleware (or the command) will be executed.
+- If it returns false, the execution chain stops immediately (the command will not run).
+
+### Adding Middleware
+Use `AddMiddleware` on a plugin to add one or more shared middleware functions. They are executed in the order they are added.
+
+```go
+plugin := laniakea.NewPlugin[*MyDB]("admin")
+plugin.AddMiddleware(laniakea.NewMiddleware("logging", loggingMiddleware))
+plugin.AddMiddleware(laniakea.NewMiddleware("admin-only", adminOnlyMiddleware))
+plugin.Command("ban", banUser)
+```
+
+### Example Middlewares
+
+1. Logging Middleware – logs every command execution.
+```go
+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
+}
+```
+
+2. Admin-Only Middleware – restricts access to users with a specific role.
+```go
+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
+    }
+    return true
+}
+```
+
+### Important Notes
+- 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`. `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(...)` 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.
+- Non-command updates can be routed with `plugin.AddUpdateHandler(updateType, handler)`.
+- `message`, `channel_post`, and `callback_query` stay on the command/payload flow.
+- `tgapi.Update` exposes a derived `Type` field after JSON unmarshalling so handlers can inspect the effective update kind directly.
+
+## 📝 License
+
+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.scuroneko.dev/scuroneko/laniakea)
+
+[Wiki](https://git.scuroneko.dev/ScuroNeko/Laniakea/wiki)
+
+[Telegram Bot API](https://core.telegram.org/bots/api)
+
+    ✅ Built with ❤️ by scuroneko

README_RU.md

@@ -0,0 +1,371 @@
+# Laniakea
+
+![Laniakea](assets/logo.jpg)
+
+[![Go Version](https://img.shields.io/badge/Go-1.26+-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.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)
+
+---
+
+## ✨ Возможности
+
+*   **Простой и интуитивный API:** Разработан для лёгкости использования, основан на практических примерах.
+*   **Система плагинов:** Организуйте функциональность бота в независимые, переиспользуемые плагины.
+*   **Обработка команд:** Легко регистрируйте команды и извлекайте аргументы.
+*   **Поддержка промежуточных слоёв (Middleware):** Выполняйте код до или после команд (например, логирование, проверка доступа).
+*   **Автоматическая генерация команд:** Генерируйте справку и списки команд автоматически.
+*   **Встроенный ограничитель запросов (Rate Limiter):** Защитите бота от превышения лимитов Telegram API (с обработкой `retry_after`).
+*   **Контекст данных:** Передавайте общие данные приложения или state в обработчики.
+*   **Настраиваемый API:** Комбинируйте `Set...` и `Add...` helper-методы для понятной конфигурации, например `bot.SetErrorTemplate(...).AddPlugins(...)`.
+*   **Polling и Webhook Runtime:** Запускайте бота через long polling с `Run()` / `RunWithContext(...)` или через webhook server, которым владеет сам бот, с `RunWebhookWithContext(...)`.
+
+---
+
+## 📦 Установка
+
+```bash
+go get git.scuroneko.dev/scuroneko/laniakea
+```
+
+или
+
+```bash
+go get github.com/scuroneko/laniakea
+```
+
+## 🚀 Быстрый старт (с пошаговыми комментариями)
+Вот минимальный пример бота "echo/ping" с подробными комментариями.
+
+```go
+package main
+
+import (
+	"log"
+
+	"git.scuroneko.dev/scuroneko/laniakea" // Импортируем библиотеку Laniakea
+)
+
+// echo — это функция-обработчик команды.
+// Она получает два параметра:
+//   - ctx: контекст сообщения (содержит информацию о сообщении, отправителе, чате и т.д.)
+//   - data: ваши общие данные приложения (здесь мы используем NoData — заглушку без общих зависимостей)
+func echo(ctx *laniakea.MessageContext, data laniakea.NoData) error {
+	// Отвечаем пользователю текстом, который он прислал, без префикса команды.
+	// ctx.Text содержит сообщение пользователя, из которого удалена часть с командой.
+	ctx.Answer(ctx.Text) // Ввод пользователя БЕЗ команды
+	return nil
+}
+
+func main() {
+	// 1. Создаём опции бота. Замените "TOKEN" на реальный токен от @BotFather.
+	opts := &laniakea.BotOpts{Token: "TOKEN"}
+
+	// 2. Инициализируем новый экземпляр бота.
+	//    Используем laniakea.NoData как тип данных приложения (общие зависимости не нужны для примера).
+	bot, err := laniakea.NewBot[laniakea.NoData](opts)
+	if err != nil {
+		log.Fatal(err)
+	}
+	// Гарантируем освобождение ресурсов бота при выходе.
+	defer bot.Close()
+
+	// 3. Создаём новый плагин с именем "ping".
+	//    Плагины помогают группировать связанные команды и промежуточные обработчики.
+	p := laniakea.NewPlugin[laniakea.NoData]("ping")
+
+	// 4. Добавляем команду в плагин.
+	//    p.Command("echo", echo) создаёт команду, которая вызывает функцию 'echo' по команде "/echo".
+	p.Command("echo", echo)
+
+	// 5. Добавляем ещё одну команду, используя анонимную функцию (замыкание).
+	//    Эта команда просто отвечает "Pong", когда пользователь отправляет "/ping".
+	p.Command("ping", func(ctx *laniakea.MessageContext, data laniakea.NoData) error {
+		ctx.Answer("Pong")
+		return nil
+	})
+
+	// 6. Настраиваем бота: задаём шаблон ошибки и добавляем плагин.
+	//    SetErrorTemplate устанавливает формат для сообщений об ошибках (где %s будет заменён на текст ошибки).
+	//    AddPlugins(p) регистрирует наш плагин "ping" в боте.
+	bot = bot.SetErrorTemplate("Ошибка\n\n%s").AddPlugins(p)
+
+	// 7. Автоматически генерируем команды, такие как /start, /help и список всех зарегистрированных команд.
+	//    Это необязательно, но очень полезно для большинства ботов.
+	if err := bot.AutoGenerateCommands(); err != nil {
+		log.Println(err)
+	}
+
+	// 8. Запускаем бота, начиная прослушивание обновлений (long polling).
+	if err := bot.Run(); err != nil {
+		log.Fatal(err)
+	}
+}
+```
+
+### Как это работает
+1. `BotOpts`: Содержит конфигурацию, например, токен API.
+2. `NewBot[T]`: Создаёт экземпляр бота. Параметр типа T позволяет передать общие данные приложения (например, *sql.DB или контейнер сервисов), которые будут доступны во всех обработчиках. Используйте laniakea.NoData, если они не нужны.
+3. `NewPlugin`: Создаёт логическую группу для команд и Middleware.
+4. `Command`: Создаёт и регистрирует команду. Первый аргумент — имя команды без слеша, второй — функция-обработчик (`func(*MessageContext, T) error`).
+5. **Функции-обработчики**: Получают *MessageContext (детали сообщения, методы типа Answer) и ваши данные приложения типа T, а ошибку возвращают для централизованной обработки.
+6. `SetErrorTemplate`: Устанавливает шаблон для сообщений об ошибках. Плейсхолдер %s заменяется на текст ошибки.
+7. `AutoGenerateCommands`: Регистрирует команды из плагинов в Telegram для поддерживаемых scope.
+8. `Run()`: Запускает цикл опроса обновлений бота и возвращает ошибку, если старт или polling завершился неуспешно.
+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)
+Плагины — основной способ организации кода. Плагин может содержать несколько команд и Middleware.
+
+```go
+plugin := laniakea.NewPlugin[*MyDB]("admin")
+plugin.Command("ban", banUser)
+bot.AddPlugins(plugin)
+```
+
+### Команды (Commands)
+Команда — это функция, которая обрабатывает конкретную команду бота (например, /start).
+
+```go
+func myHandler(ctx *laniakea.MessageContext, db *MyDB) error {
+    // Доступ к аргументам команды через ctx.Args ([]string)
+    // Ответ пользователю: ctx.Answer("какой-то текст")
+    return nil
+}
+```
+
+### Контекст сообщения (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.
+- `AnswerPhotoMarkdown(photoID, text string) *AnswerMessage`: Отправляет фотографию с подписью, отформатированной MarkdownV2 (экранирование на вашей стороне).
+- `EditCallback(text string, keyboard *InlineKeyboard) *AnswerMessage`: Редактирует сообщение с `parse_mode` none после нажатия inline-кнопки.
+- `EditCallbackMarkdown(text string, keyboard *InlineKeyboard) *AnswerMessage`: Редактирует сообщение в формате MarkdownV2 (экранирование на вашей стороне) после нажатия inline-кнопки.
+- `SendAction(action tgapi.ChatActionType)`: Отправляет действие "печатает", "загружает фото" и т.д.
+- Поля: `Text`, `Args`, `From`, `FromID`, `Msg`, `InlineMsgID`, `CallbackQueryID` и другие.
+- И много других методов и полей!
+
+### App Data
+Параметр типа `T` в `NewBot[T]` — мощная возможность. Вы можете передать любой тип, но для разделяемых зависимостей вроде пула соединений с БД, контейнера сервисов или API-клиента обычно стоит использовать pointer type.
+
+```go
+type MyDB struct { /* ... */ }
+db := &MyDB{...}
+bot, err := laniakea.NewBot[*MyDB](opts)
+if err != nil {
+    log.Fatal(err)
+}
+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` есть два клиента:
+
+- `API` для JSON-запросов (`SendMessage`, `EditMessageText`, методы с `file_id`/URL).
+- `Uploader` для multipart-загрузок (`SendPhoto`, `SendDocument`, `SendVideo` с бинарными файлами).
+
+Для продвинутых сценариев `tgapi.NewRequest(...)` и `tgapi.NewUploaderRequest(...)` остаются публичными low-level escape hatch API. Они менее безопасны, чем типизированные helper-методы: вызывающая сторона сама отвечает за корректное имя Telegram-метода и совместимые типы параметров/ответа.
+
+## 🧩 Промежуточные слои (Middleware)
+Middleware — это функции, которые выполняются перед обработчиком команды. Они идеально подходят для сквозных задач, таких как логирование, контроль доступа, ограничение скорости запросов или модификация контекста.
+
+### Сигнатура
+Функция middleware имеет ту же сигнатуру, что и обработчик команды, но должна возвращать bool:
+
+```go
+func(ctx *MessageContext, db T) bool
+```
+
+- Если возвращается true, выполняется следующий middleware (или сама команда).
+- Если возвращается false, цепочка выполнения немедленно прерывается (команда не запускается).
+
+### Добавление middleware
+Используйте метод `AddMiddleware` плагина для добавления одной или нескольких функций middleware. Они выполняются в порядке добавления.
+
+```go
+plugin := laniakea.NewPlugin[*MyDB]("admin")
+plugin.AddMiddleware(laniakea.NewMiddleware("logging", loggingMiddleware))
+plugin.AddMiddleware(laniakea.NewMiddleware("admin-only", adminOnlyMiddleware))
+plugin.Command("ban", banUser)
+```
+
+### Примеры middleware
+
+1. Логирующий middleware – логирует каждое выполнение команды.
+```go
+func loggingMiddleware(ctx *laniakea.MessageContext, db *MyDB) bool {
+    log.Printf("Пользователь %d выполнил команду: %s", ctx.FromID, ctx.Msg.Text)
+    return true // продолжаем к следующему middleware/команде
+}
+```
+
+2. Middleware только для администраторов – ограничивает доступ пользователям с определённой ролью.
+```go
+func adminOnlyMiddleware(ctx *laniakea.MessageContext, db *MyDB) bool {
+    if !db.IsAdmin(ctx.FromID) { // предполагается, что db имеет метод IsAdmin
+        ctx.Answer("⛔ Доступ запрещён. Только для администраторов.")
+        return false // останавливаем выполнение
+    }
+    return true
+}
+```
+
+### Важные замечания
+- Middleware может изменять MessageContext (например, добавлять пользовательские поля) перед запуском команды.
+
+## ⚙️ Расширенная настройка
+- **Инлайн-клавиатуры**: Создавайте клавиатуры с помощью `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(...)` и `RunWebhookWithContext(...)` не вызывают `Close()` автоматически. Завершайте бот явно и создавайте новый `Bot` для следующего запуска.
+
+## Обработка Telegram Updates
+- Команды и payload-ы обрабатываются через плагины.
+- Для некомандных update-ов можно зарегистрировать обработчик через `plugin.AddUpdateHandler(updateType, handler)`.
+- `message`, `channel_post` и `callback_query` остаются в command/payload flow.
+- После JSON-декодирования `tgapi.Update` заполняет поле `Type`, чтобы обработчики могли явно видеть итоговый вид update.
+
+## 📝 Лицензия
+Этот проект лицензирован под GNU General Public License v3.0 - подробности см. в файле [LICENSE](LICENSE).
+
+## 📚 Дополнительная информация
+[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)
+
+    ✅ Создано с ❤️ scuroneko

SEMVER.md

@@ -0,0 +1,45 @@
+# Semantic Versioning Policy
+
+This project follows Semantic Versioning with the rules below.
+
+## Public API Surface
+
+The public API consists of:
+- exported identifiers in package `laniakea`
+- exported identifiers in package `tgapi`
+- documented behavior in `README.md`, `README_RU.md`, and package godoc
+
+Anything unexported is internal and may change without notice.
+
+## Breaking Changes
+
+A release requires a major version bump when it changes any of the following:
+- exported function, method, type, field, constant, or variable names
+- function or method signatures
+- JSON field names or request/response wire compatibility in `tgapi`
+- documented behavioral guarantees relied on by callers
+
+Examples:
+- removing an exported alias
+- changing callback payload encoding defaults
+- changing handler dispatch semantics in a way that breaks existing bots
+
+## Minor Changes
+
+A release uses a minor version bump for backward-compatible additions:
+- new exported types, methods, helpers, or update handlers
+- support for new Telegram Bot API fields or methods
+- optional configuration knobs that do not change existing defaults
+
+## Patch Changes
+
+A release uses a patch version bump for backward-compatible fixes:
+- bug fixes
+- test-only changes
+- godoc and README clarifications
+- internal refactors with no public behavior change
+
+## Pre-Releases
+
+`-rc.N` builds may still adjust API details before `v1.0.0`.
+Once `v1.0.0` is released, breaking changes require a new major version.

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

@@ -1,281 +1,547 @@
 package laniakea
 
 import (
+	"context"
+	"errors"
 	"fmt"
-	"os"
-	"sort"
-	"strings"
+	"net/http"
+	"sync"
 	"time"
 
-	"git.nix13.pw/scuroneko/extypes"
-	"git.nix13.pw/scuroneko/laniakea/tgapi"
-	"git.nix13.pw/scuroneko/slog"
+	"git.scuroneko.dev/scuroneko/extypes"
+	"git.scuroneko.dev/scuroneko/laniakea/tgapi"
+	"git.scuroneko.dev/scuroneko/laniakea/utils"
+	"git.scuroneko.dev/scuroneko/sneklog/v2"
 )
 
-type BotOpts struct {
-	Token            string
-	Debug            bool
-	ErrorTemplate    string
-	Prefixes         []string
-	UpdateTypes      []string
-	LoggerBasePath   string
-	UseRequestLogger bool
-	WriteToFile      bool
-	UseTestServer    bool
-	APIUrl           string
+// AppData is the generic shared application data type injected into bots,
+// plugins, and handlers.
+//
+// Use it for long-lived shared dependencies such as database handles, service
+// containers, API clients, or immutable configuration snapshots.
+//
+// Example:
+//
+//	type MyDB struct { ... }
+//	myDB := &MyDB{}
+//	bot, err := NewBot[*MyDB](opts)
+//	if err != nil {
+//		return err
+//	}
+//	bot.SetAppData(myDB)
+//
+// Use NoData if no shared application data is needed.
+type AppData any
+
+// NoData is a placeholder type for bots that do not use shared application
+// data.
+//
+// Use Bot[NoData] to indicate no shared dependency injection is required.
+type NoData struct{}
+
+// AppDataLogger builds a sneklog.LoggerWriter from injected application data.
+//
+// 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
+
+const (
+	// BotPayloadBase64 encodes callback data as a Base64 string.
+	BotPayloadBase64 BotPayloadType = "base64"
+	// BotPayloadJSON encodes callback data as a JSON string.
+	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 (
+	// ErrNoPrefixes reports that the bot was started without any command prefixes.
+	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, RunWithContext, or RunWebhookWithContext was called more than once.
+	ErrBotAlreadyRun = errors.New("bot can only be run once")
+
+	// ErrTokenRequired reports that BotOpts.Token was empty.
+	ErrTokenRequired = errors.New("token required")
+	// ErrOptsIsNil reports that NewBot was called with a nil BotOpts pointer.
+	ErrOptsIsNil = errors.New("opts is nil")
+)
+
+// Bot is the core Telegram bot instance.
+//
+// Manages:
+//   - API communication via tgapi
+//   - Update processing pipeline (middleware → plugins)
+//   - Background runners
+//   - Logging and rate limiting
+//   - Localization and draft message support
+//
+// Runtime accessors are safe for concurrent use. Configure the bot before Run,
+// RunWithContext, or RunWebhookWithContext.
+// A Bot is single-use: after Run, RunWithContext, or RunWebhookWithContext returns,
+// create a new Bot for the next session.
+type Bot[T AppData] struct {
+	token             string
+	debug             bool
+	errorTemplate     string
+	userID            int64
+	username          string
+	payloadType       BotPayloadType
+	strictPayloadType bool
+	maxWorkers        int
+	pollTimeout       int // Long-polling timeout in seconds for getUpdates
+
+	logFormat     utils.LogFormat
+	logFormatter  *sneklog.Formatter
+	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)
+	prefixes    []string        // Command prefixes (e.g., "/", "!")
+	runners     []Runner[T]     // Background tasks (e.g., cleanup, cron)
+
+	api           *tgapi.API      // Telegram API client
+	uploader      *tgapi.Uploader // File uploader
+	l10n          *L10n           // Localization manager
+	draftProvider *DraftProvider  // Draft message builder
+	observer      Observer        // Optional event observer for instrumentation
+
+	appData         T // Injected application data
+	hasAppData      bool
+	warnedValueData bool
+
+	sessionStore       SessionStore // Session store for scene management
+	sceneScopePriority []SceneScope
+	sceneLocks         sceneKeyLocker
+
+	updateOffsetMu sync.Mutex
+	updateOffset   int                // Last processed update ID
+	updateTypes    []tgapi.UpdateType // Types of updates to fetch
+	updateQueue    chan *tgapi.Update // Internal queue for processing updates
+	runnerOnceWG   sync.WaitGroup     // Tracks one-time async runners
+	runnerBgWG     sync.WaitGroup     // Tracks background async runners
+	runStateMu     sync.Mutex
+	running        bool
+	ran            bool
 }
 
-func LoadOptsFromEnv() *BotOpts {
-	return &BotOpts{
-		Token:            os.Getenv("TG_TOKEN"),
-		Debug:            os.Getenv("DEBUG") == "true",
-		ErrorTemplate:    os.Getenv("ERROR_TEMPLATE"),
-		Prefixes:         LoadPrefixesFromEnv(),
-		UpdateTypes:      strings.Split(os.Getenv("UPDATE_TYPES"), ";"),
-		UseRequestLogger: os.Getenv("USE_REQ_LOG") == "true",
-		WriteToFile:      os.Getenv("WRITE_TO_FILE") == "true",
-		UseTestServer:    os.Getenv("USE_TEST_SERVER") == "true",
-		APIUrl:           os.Getenv("API_URL"),
+func (bot *Bot[T]) configMutable(method string) bool {
+	bot.runStateMu.Lock()
+	defer bot.runStateMu.Unlock()
+	if !bot.ran {
+		return true
 	}
-}
-func LoadPrefixesFromEnv() []string {
-	prefixesS, exists := os.LookupEnv("PREFIXES")
-	if !exists {
-		return []string{"/"}
+	if bot.logger != nil {
+		bot.logger.Warnln(fmt.Sprintf("%s called after bot configuration was frozen; ignoring", method))
 	}
-	return strings.Split(prefixesS, ";")
+	return false
 }
 
-type DbContext interface{}
-type Bot[T DbContext] struct {
-	token         string
-	debug         bool
-	errorTemplate string
+// NewBot creates and initializes a new Bot instance using the provided BotOpts.
+//
+// Automatically:
+//   - Creates API and Uploader clients
+//   - Initializes structured logging (JSON stdout + optional file)
+//   - Fetches bot username via GetMe()
+//   - Sets up DraftProvider with random IDs
+//   - Adds API and Uploader loggers to extraLoggers
+func NewBot[T any](opts *BotOpts) (*Bot[T], error) {
+	if opts == nil {
+		return nil, ErrOptsIsNil
+	}
+	if opts.Token == "" {
+		return nil, ErrTokenRequired
+	}
 
-	logger        *slog.Logger
-	RequestLogger *slog.Logger
+	updateQueue := make(chan *tgapi.Update, 512)
 
-	plugins     []Plugin[T]
-	middlewares []Middleware[T]
-	prefixes    []string
-	runners     []Runner[T]
+	limiter := utils.NewRateLimiter()
+	limiter.SetGlobalRate(opts.RateLimit)
 
-	api       *tgapi.API
-	uploader  *tgapi.Uploader
-	dbContext *T
-	l10n      *L10n
+	workers := 32
+	if opts.MaxWorkers > 0 {
+		workers = opts.MaxWorkers
+	}
 
-	dbWriterRequested extypes.Slice[*slog.Logger]
+	pollTimeout := 30
+	if opts.PollTimeout > 0 {
+		pollTimeout = opts.PollTimeout
+	}
 
-	updateOffset int
-	updateTypes  []tgapi.UpdateType
-	updateQueue  *extypes.Queue[*tgapi.Update]
-}
-
-func NewBot[T any](opts *BotOpts) *Bot[T] {
-	updateQueue := extypes.CreateQueue[*tgapi.Update](512)
-
-	apiOpts := tgapi.NewAPIOpts(opts.Token).SetAPIUrl(opts.APIUrl).UseTestServer(opts.UseTestServer)
+	// 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).
+		UseTestServer(opts.UseTestServer).
+		SetLimiter(limiter).
+		SetDropRateLimitOverflow(opts.DropRateLimitOverflow).
+		SetLogFormat(opts.LogFormat).
+		SetLogFormatter(opts.LogFormatter).
+		SetHTTPClient(&http.Client{Timeout: httpTimeout})
 	api := tgapi.NewAPI(apiOpts)
-
 	uploader := tgapi.NewUploader(api)
 
+	prefixes := append([]string(nil), opts.Prefixes...)
+	if len(prefixes) == 0 {
+		prefixes = []string{"/"}
+	}
+
 	bot := &Bot[T]{
 		updateOffset:      0,
 		errorTemplate:     "%s",
+		payloadType:       BotPayloadBase64,
+		strictPayloadType: opts.StrictPayloadType,
+		maxWorkers:        workers,
+		pollTimeout:       pollTimeout,
 		updateQueue:       updateQueue,
 		api:               api,
 		uploader:          uploader,
 		debug:             opts.Debug,
-		prefixes:          opts.Prefixes,
+		prefixes:          prefixes,
 		token:             opts.Token,
-		plugins:           make([]Plugin[T], 0),
-		updateTypes:       make([]tgapi.UpdateType, 0),
-		runners:           make([]Runner[T], 0),
-		dbWriterRequested: make([]*slog.Logger, 0),
-		l10n:              &L10n{},
+		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([]*sneklog.Logger, 0),
+		l10n:          &L10n{},
+		draftProvider: NewRandomDraftProvider(api),
+
+		sessionStore:       NewMemorySessionStore(),
+		sceneScopePriority: []SceneScope{SceneScopeUserChat, SceneScopeChat, SceneScopeUser},
 	}
-	bot.dbWriterRequested = bot.dbWriterRequested.Push(api.GetLogger()).Push(uploader.GetLogger())
+
+	// Add API and Uploader loggers to extraLoggers for unified output
+	bot.extraLoggers = bot.extraLoggers.Push(api.GetLogger()).Push(uploader.GetLogger())
 
 	if len(opts.ErrorTemplate) > 0 {
 		bot.errorTemplate = opts.ErrorTemplate
 	}
-	if len(opts.LoggerBasePath) == 0 {
-		opts.LoggerBasePath = "./"
+	loggerOpts := *opts
+	if len(loggerOpts.LoggerBasePath) == 0 {
+		loggerOpts.LoggerBasePath = "./"
 	}
-	bot.initLoggers(opts)
+	bot.initLoggers(&loggerOpts)
 
+	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 {
-		_ = api.CloseApi()
-		_ = uploader.Close()
-		bot.logger.Fatal(err)
+		_ = bot.Close()
+		return nil, err
 	}
-	bot.logger.Infof("Authorized as %s\n", u.FirstName)
+	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 and RunWebhookWithContext do not call Close automatically.
+// 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 {
-	if err := bot.uploader.Close(); err != nil {
-		bot.logger.Errorln(err)
+	var e []error
+	logCloseErr := func(err error) {
+		if err == nil {
+			return
+		}
+		if bot.logger != nil {
+			bot.logger.Errorln(err)
+		}
+		e = append(e, err)
 	}
-	if err := bot.api.CloseApi(); err != nil {
-		bot.logger.Errorln(err)
+
+	for _, p := range bot.plugins {
+		if err := p.Close(); err != nil {
+			e = append(e, err)
+		}
 	}
-	if err := bot.RequestLogger.Close(); err != nil {
-		bot.logger.Errorln(err)
+	if bot.webhookLogger != nil {
+		if err := bot.webhookLogger.Close(); err != nil {
+			logCloseErr(err)
+		}
+		bot.webhookLogger = nil
 	}
-	if err := bot.logger.Close(); err != nil {
+	if bot.uploader != nil {
+		if err := bot.uploader.Close(); err != nil {
+			logCloseErr(err)
+		}
+	}
+	if bot.api != nil {
+		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...)
+}
+
+// CloseRemote sends Telegram Bot API "close" request for the current bot
+// instance using ctx for cancellation and deadlines.
+//
+// This is separate from Bot.Close(), which only releases local resources.
+func (bot *Bot[T]) CloseRemote(ctx context.Context) error {
+	if _, err := bot.api.CloseRemoteWithContext(ctx); err != nil {
 		return err
 	}
 	return nil
 }
-func (bot *Bot[T]) initLoggers(opts *BotOpts) {
-	level := slog.FATAL
-	if opts.Debug {
-		level = slog.DEBUG
-	}
 
-	bot.logger = slog.CreateLogger().Level(level).Prefix("BOT")
-	bot.logger.AddWriter(bot.logger.CreateJsonStdoutWriter())
-	if opts.WriteToFile {
-		path := fmt.Sprintf("%s/main.log", strings.TrimRight(opts.LoggerBasePath, "/"))
-		fileWriter, err := bot.logger.CreateTextFileWriter(path)
-		if err != nil {
-			bot.logger.Fatal(err)
-		}
-		bot.logger.AddWriter(fileWriter)
-	}
+// GetUpdateOffset returns the current update offset (thread-safe).
+func (bot *Bot[T]) GetUpdateOffset() int {
+	bot.updateOffsetMu.Lock()
+	defer bot.updateOffsetMu.Unlock()
+	return bot.updateOffset
+}
 
-	if opts.UseRequestLogger {
-		bot.RequestLogger = slog.CreateLogger().Level(level).Prefix("REQUESTS")
-		bot.RequestLogger.AddWriter(bot.RequestLogger.CreateJsonStdoutWriter())
-		if opts.WriteToFile {
-			path := fmt.Sprintf("%s/requests.log", strings.TrimRight(opts.LoggerBasePath, "/"))
-			fileWriter, err := bot.RequestLogger.CreateTextFileWriter(path)
-			if err != nil {
-				bot.logger.Fatal(err)
-			}
-			bot.RequestLogger.AddWriter(fileWriter)
-		}
+// SetUpdateOffset sets the update offset for next GetUpdates call (thread-safe).
+func (bot *Bot[T]) SetUpdateOffset(offset int) {
+	bot.updateOffsetMu.Lock()
+	defer bot.updateOffsetMu.Unlock()
+	bot.updateOffset = offset
+}
+
+// GetLogger returns the main bot logger.
+func (bot *Bot[T]) GetLogger() *sneklog.Logger { return bot.logger }
+
+// GetRequestLogger returns the request-level logger, if configured.
+func (bot *Bot[T]) GetRequestLogger() *sneklog.Logger { return bot.requestLogger }
+
+// 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() sneklog.LogLevel {
+	level := sneklog.FATAL
+	if bot.debug {
+		level = sneklog.DEBUG
 	}
+	return level
 }
 
-func (bot *Bot[T]) GetUpdateOffset() int                    { return bot.updateOffset }
-func (bot *Bot[T]) SetUpdateOffset(offset int)              { bot.updateOffset = offset }
-func (bot *Bot[T]) GetUpdateTypes() []tgapi.UpdateType      { return bot.updateTypes }
-func (bot *Bot[T]) GetQueue() *extypes.Queue[*tgapi.Update] { return bot.updateQueue }
-func (bot *Bot[T]) GetLogger() *slog.Logger                 { return bot.logger }
-func (bot *Bot[T]) GetDBContext() *T                        { return bot.dbContext }
-func (bot *Bot[T]) L10n(lang, key string) string            { return bot.l10n.Translate(lang, key) }
-
-func (bot *Bot[T]) AddDatabaseLogger(writer func(db *T) slog.LoggerWriter) *Bot[T] {
-	w := writer(bot.dbContext)
-	bot.logger.AddWriter(w)
-	if bot.RequestLogger != nil {
-		bot.RequestLogger.AddWriter(w)
-	}
-	for _, l := range bot.dbWriterRequested {
-		l.AddWriter(w)
-	}
-	return bot
+// L10n translates a key in the given language.
+// Returns key if translation not found.
+func (bot *Bot[T]) L10n(lang, key string) string {
+	return bot.l10n.Translate(lang, key)
 }
 
-func (bot *Bot[T]) DatabaseContext(ctx *T) *Bot[T] {
-	bot.dbContext = ctx
-	return bot
-}
-func (bot *Bot[T]) UpdateTypes(t ...tgapi.UpdateType) *Bot[T] {
-	bot.updateTypes = make([]tgapi.UpdateType, 0)
-	bot.updateTypes = append(bot.updateTypes, t...)
-	return bot
-}
-func (bot *Bot[T]) AddUpdateType(t ...tgapi.UpdateType) *Bot[T] {
-	bot.updateTypes = append(bot.updateTypes, t...)
-	return bot
-}
-func (bot *Bot[T]) AddPrefixes(prefixes ...string) *Bot[T] {
-	bot.prefixes = append(bot.prefixes, prefixes...)
-	return bot
-}
-func (bot *Bot[T]) ErrorTemplate(s string) *Bot[T] {
-	bot.errorTemplate = s
-	return bot
-}
-func (bot *Bot[T]) Debug(debug bool) *Bot[T] {
-	bot.debug = debug
-	return bot
-}
-func (bot *Bot[T]) AddPlugins(plugin ...*Plugin[T]) *Bot[T] {
-	for _, p := range plugin {
-		bot.plugins = append(bot.plugins, *p)
-		bot.logger.Debugln(fmt.Sprintf("plugins with name \"%s\" registered", p.Name))
-	}
-	return bot
-}
-func (bot *Bot[T]) AddMiddleware(middleware ...Middleware[T]) *Bot[T] {
-	bot.middlewares = append(bot.middlewares, middleware...)
-	for _, m := range middleware {
-		bot.logger.Debugln(fmt.Sprintf("middleware with name \"%s\" registered", m.name))
-	}
-
-	sort.Slice(bot.middlewares, func(i, j int) bool {
-		first := bot.middlewares[i]
-		second := bot.middlewares[j]
-		if first.order == second.order {
-			return first.name < second.name
-		}
-		return first.order < second.order
-	})
-
-	return bot
-}
-func (bot *Bot[T]) AddRunner(runner Runner[T]) *Bot[T] {
-	bot.runners = append(bot.runners, runner)
-	bot.logger.Debugln(fmt.Sprintf("runner with name \"%s\" registered", runner.name))
-	return bot
-}
-func (bot *Bot[T]) AddL10n(l *L10n) *Bot[T] {
-	bot.l10n = l
-	return bot
-}
-
-func (bot *Bot[T]) Run() {
+// RunWithContext starts the bot with a given context for graceful shutdown.
+//
+// This is the main entry point for bot execution. It:
+//   - Validates required configuration (prefixes, plugins)
+//   - Starts all registered runners as background goroutines
+//   - Begins polling for updates via Telegram's GetUpdates API
+//   - Processes updates concurrently using a worker pool with size configurable via BotOpts.MaxWorkers
+//
+// The context controls graceful shutdown. When canceled, the bot:
+//   - Stops polling for new updates
+//   - 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.
+//
+// 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 {
-		bot.logger.Fatalln("no prefixes defined")
-		return
+		return ErrNoPrefixes
 	}
 
 	if len(bot.plugins) == 0 {
-		bot.logger.Fatalln("no plugins defined")
-		return
+		return ErrNoPlugins
+	}
+	if err := bot.beginRun(); err != nil {
+		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()
+	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)
+		}()
+		backoffDelay := time.Duration(0)
+		retryCount := 0
 		for {
-			_, err := bot.Updates()
-			if err != nil {
-				bot.logger.Errorln(err)
+			select {
+			case <-ctx.Done():
+				return
+			default:
+				updates, err := bot.Updates(ctx)
+				if err != nil {
+					if ctx.Err() != nil {
+						return
+					}
+					retryDelay, ok := pollRetryAfterDelay(err)
+					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():
+						if !timer.Stop() {
+							<-timer.C
+						}
+						return
+					case <-timer.C:
+					}
+					continue
+				}
+				backoffDelay = 0
+				retryCount = 0
+
+				for _, update := range updates {
+					if err := bot.enqueueUpdate(ctx, update); err != nil {
+						return
+					}
+				}
 			}
 		}
 	}()
 
-	for {
-		queue := bot.updateQueue
-		if queue.IsEmpty() {
-			time.Sleep(time.Millisecond * 25)
-			continue
-		}
+	bot.logger.Infoln("Bot running. Press CTRL+C to exit.")
+	// Start worker pool for concurrent update handling
+	bot.startUpdateWorkers(ctx)
 
-		u := queue.Dequeue()
-		if u == nil {
-			bot.logger.Errorln("update is nil")
-			continue
-		}
+	bot.runnerOnceWG.Wait()
+	bot.runnerBgWG.Wait()
+	return nil
+}
 
-		bot.handle(u)
-	}
+// Run starts the bot using a background context.
+//
+// Equivalent to RunWithContext(context.Background()).
+// Use this for simple bots where graceful shutdown is not required.
+//
+// For production use, prefer RunWithContext to handle SIGINT/SIGTERM gracefully.
+func (bot *Bot[T]) Run() error {
+	return bot.RunWithContext(context.Background())
 }

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

@@ -0,0 +1,320 @@
+package laniakea
+
+import (
+	"os"
+	"strconv"
+	"strings"
+
+	"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.
+//
+// Values are loaded from environment variables via LoadOptsFromEnv().
+// Use &BotOpts{} to create a value and set fields manually.
+type BotOpts struct {
+	// Token is the Telegram bot token (required).
+	Token string
+
+	// UpdateTypes is a list of update types to listen for.
+	// Example: "["message", "edited_message", "callback_query"]"
+	// Defaults to empty (Telegram will return all types).
+	UpdateTypes []tgapi.UpdateType
+
+	// Debug enables debug-level logging.
+	Debug bool
+
+	// ErrorTemplate is the format string used to wrap error messages sent to users.
+	// Use "%s" to insert the actual error. Example: "❌ Error: %s"
+	ErrorTemplate string
+
+	// Prefixes is a list of command prefixes (e.g., ["/", "!"]).
+	// Defaults to ["/"] if not set via environment.
+	Prefixes []string
+
+	// LoggerBasePath is the directory where log files are written.
+	// Defaults to "./".
+	LoggerBasePath string
+
+	// UseRequestLogger enables detailed logging of all Telegram API requests.
+	UseRequestLogger bool
+
+	// WriteToFile enables writing logs to files (main.log and requests.log).
+	WriteToFile bool
+
+	// UseTestServer uses Telegram's test server (https://api.test.telegram.org).
+	UseTestServer bool
+
+	// APIURL overrides the default Telegram API endpoint (useful for proxies or self-hosted).
+	APIURL string
+
+	// RateLimit is the maximum number of API requests per second.
+	// Telegram allows up to 30 req/s for most bots. Defaults to 30.
+	RateLimit int
+
+	// DropRateLimitOverflow drops incoming updates when rate limit is exceeded instead of queuing.
+	// Use this to prioritize responsiveness over reliability.
+	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.
+//
+// Environment variables:
+//   - TG_TOKEN: Bot token (required)
+//   - UPDATE_TYPES: semicolon-separated update types (e.g., "message;callback_query")
+//   - DEBUG: "true" to enable debug logging
+//   - ERROR_TEMPLATE: format string for error messages (e.g., "❌ %s")
+//   - PREFIXES: semicolon-separated prefixes (e.g., "/;!bot")
+//   - LOGGER_BASE_PATH: directory for log files (default: "./")
+//   - USE_REQ_LOG: "true" to enable request logging
+//   - WRITE_TO_FILE: "true" to write logs to files
+//   - USE_TEST_SERVER: "true" to use Telegram test server
+//   - API_URL: custom API endpoint
+//   - RATE_LIMIT: max requests per second (default: 30)
+//   - DROP_RL_OVERFLOW: "true" to drop updates on rate limit overflow
+//   - 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))
+	for _, updateType := range stringUpdateTypes {
+		updateTypes = append(updateTypes, tgapi.UpdateType(updateType))
+	}
+
+	if rl := os.Getenv("RATE_LIMIT"); rl != "" {
+		if n, err := strconv.Atoi(rl); err == nil {
+			rateLimit = n
+		}
+	}
+
+	if mw := os.Getenv("MAX_WORKERS"); mw != "" {
+		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,
+
+		Debug:         os.Getenv("DEBUG") == "true",
+		ErrorTemplate: os.Getenv("ERROR_TEMPLATE"),
+		Prefixes:      LoadPrefixesFromEnv(),
+
+		LoggerBasePath:   os.Getenv("LOGGER_BASE_PATH"),
+		UseRequestLogger: os.Getenv("USE_REQ_LOG") == "true",
+		WriteToFile:      os.Getenv("WRITE_TO_FILE") == "true",
+
+		UseTestServer: os.Getenv("USE_TEST_SERVER") == "true",
+		APIURL:        os.Getenv("API_URL"),
+
+		RateLimit:             rateLimit,
+		DropRateLimitOverflow: os.Getenv("DROP_RL_OVERFLOW") == "true",
+		StrictPayloadType:     os.Getenv("STRICT_PAYLOAD_TYPE") == "true",
+
+		MaxWorkers:        maxWorkers,
+		PollTimeout:       pollTimeout,
+		FileConfigVersion: 0,
+		LogFormat:         utils.LogFormat(os.Getenv("LOG_FORMAT")),
+	}
+}
+
+// SetToken sets the Telegram bot token (required).
+func (opts *BotOpts) SetToken(token string) *BotOpts {
+	opts.Token = token
+	return opts
+}
+
+// SetUpdateTypes sets the list of update types to listen for.
+// If empty (default), Telegram will return all update types.
+// Example: opts.SetUpdateTypes("message", "callback_query").
+func (opts *BotOpts) SetUpdateTypes(types ...tgapi.UpdateType) *BotOpts {
+	opts.UpdateTypes = types
+	return opts
+}
+
+// SetDebug enables or disables debug-level logging.
+// Default is false.
+func (opts *BotOpts) SetDebug(debug bool) *BotOpts {
+	opts.Debug = debug
+	return opts
+}
+
+// SetErrorTemplate sets the format string for error messages sent to users.
+// Use "%s" to insert the actual error. Example: "❌ Error: %s"
+// If not set, defaults to "%s".
+func (opts *BotOpts) SetErrorTemplate(tpl string) *BotOpts {
+	opts.ErrorTemplate = tpl
+	return opts
+}
+
+// SetPrefixes sets the command prefixes (e.g., "/", "!").
+// If not set via environment, defaults to ["/"].
+func (opts *BotOpts) SetPrefixes(prefixes ...string) *BotOpts {
+	opts.Prefixes = prefixes
+	return opts
+}
+
+// SetLoggerBasePath sets the directory where log files are written.
+// Defaults to "./".
+func (opts *BotOpts) SetLoggerBasePath(path string) *BotOpts {
+	opts.LoggerBasePath = path
+	return opts
+}
+
+// SetUseRequestLogger enables detailed logging of all Telegram API requests.
+// Default is false.
+func (opts *BotOpts) SetUseRequestLogger(use bool) *BotOpts {
+	opts.UseRequestLogger = use
+	return opts
+}
+
+// SetWriteToFile enables writing logs to files (main.log and requests.log).
+// Default is false.
+func (opts *BotOpts) SetWriteToFile(write bool) *BotOpts {
+	opts.WriteToFile = write
+	return opts
+}
+
+// SetUseTestServer enables using Telegram's test server (https://api.telegram.org/bot<token>/test).
+// Default is false.
+func (opts *BotOpts) SetUseTestServer(use bool) *BotOpts {
+	opts.UseTestServer = use
+	return opts
+}
+
+// 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 {
+	opts.APIURL = url
+	return opts
+}
+
+// SetRateLimit sets the maximum number of API requests per second.
+// Telegram allows up to 30 req/s for most bots. Defaults to 30.
+func (opts *BotOpts) SetRateLimit(limit int) *BotOpts {
+	opts.RateLimit = limit
+	return opts
+}
+
+// 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) SetDropRateLimitOverflow(drop bool) *BotOpts {
+	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
+}
+
+// SetMaxWorkers sets the maximum number of concurrent update handlers.
+// Must be called before NewBot, as the value is captured during bot creation.
+//
+// The optimal value depends on your bot's workload:
+//   - For I/O-bound handlers (e.g., database queries, external API calls), you may
+//     need more workers, but be mindful of downstream service limits.
+//   - For CPU-bound handlers, keep workers close to the number of CPU cores.
+//
+// Recommended starting points (adjust based on profiling and monitoring):
+//   - Small to medium bots with fast handlers: 16–32
+//   - Medium to large bots with fast handlers: 32–64
+//   - Large bots with heavy I/O: 64–128 (ensure your infrastructure can handle it)
+//
+// The default is 32. Monitor queue length and processing latency to fine-tune.
+func (opts *BotOpts) SetMaxWorkers(workers int) *BotOpts {
+	opts.MaxWorkers = workers
+	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 {
+	prefixesS, exists := os.LookupEnv("PREFIXES")
+	if !exists {
+		return []string{"/"}
+	}
+	prefixes := splitEnvList(prefixesS)
+	if len(prefixes) == 0 {
+		return []string{"/"}
+	}
+	return prefixes
+}
+
+func splitEnvList(value string) []string {
+	if value == "" {
+		return nil
+	}
+	parts := strings.Split(value, ";")
+	out := make([]string, 0, len(parts))
+	for _, part := range parts {
+		part = strings.TrimSpace(part)
+		if part == "" {
+			continue
+		}
+		out = append(out, part)
+	}
+	return out
+}

bot_opts_loader.go

@@ -0,0 +1,191 @@
+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)
+}
+
+// EscapeEnv escapes an environment value for use inside a JSON string.
+func (codec BotOptsFileJSONCodec) EscapeEnv(s string) string {
+	data, _ := json.Marshal(s)
+	return string(data[1 : len(data)-1])
+}
+
+var envParameterRegex = regexp.MustCompile(`\{\{\s*(\w+)\s*\}\}`)
+
+type botOptsFileEnvEscaper interface {
+	EscapeEnv(string) string
+}
+
+// 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(codec, 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(codec BotOptsFileCodec, 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))
+		if escaper, ok := codec.(botOptsFileEnvEscaper); ok {
+			value = escaper.EscapeEnv(value)
+		}
+		return []byte(value)
+	})
+}

bot_opts_loader_test.go

@@ -0,0 +1,159 @@
+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 TestLoadBotOptsFileEscapesEnvironmentValuesForJSON(t *testing.T) {
+	want := "quote: \"; slash: \\; newline:\n; tab:\t; control:\x01"
+	t.Setenv("TG_TOKEN", want)
+
+	dir := t.TempDir()
+	filename := filepath.Join(dir, "config.json")
+	if err := os.WriteFile(filename, []byte(`{"token":"{{TG_TOKEN}}"}`), 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 != want {
+		t.Fatalf("unexpected token: got %q want %q", got.Token, want)
+	}
+}
+
+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

@@ -0,0 +1,56 @@
+package laniakea
+
+import (
+	"reflect"
+	"testing"
+
+	"git.scuroneko.dev/scuroneko/laniakea/tgapi"
+)
+
+func TestLoadOptsFromEnvIgnoresEmptyUpdateTypes(t *testing.T) {
+	t.Setenv("UPDATE_TYPES", "")
+
+	opts := LoadOptsFromEnv()
+	if len(opts.UpdateTypes) != 0 {
+		t.Fatalf("expected no update types, got %v", opts.UpdateTypes)
+	}
+}
+
+func TestLoadOptsFromEnvSplitsAndTrimsUpdateTypes(t *testing.T) {
+	t.Setenv("UPDATE_TYPES", "message; ; callback_query ")
+
+	opts := LoadOptsFromEnv()
+	want := []tgapi.UpdateType{tgapi.UpdateTypeMessage, tgapi.UpdateTypeCallbackQuery}
+	if !reflect.DeepEqual(opts.UpdateTypes, want) {
+		t.Fatalf("unexpected update types: got %v want %v", opts.UpdateTypes, want)
+	}
+}
+
+func TestLoadPrefixesFromEnvDefaultsOnEmptyValue(t *testing.T) {
+	t.Setenv("PREFIXES", "")
+
+	got := LoadPrefixesFromEnv()
+	want := []string{"/"}
+	if !reflect.DeepEqual(got, want) {
+		t.Fatalf("unexpected prefixes: got %v want %v", got, want)
+	}
+}
+
+func TestLoadPrefixesFromEnvDropsEmptyValues(t *testing.T) {
+	t.Setenv("PREFIXES", "/; ; ! ")
+
+	got := LoadPrefixesFromEnv()
+	want := []string{"/", "!"}
+	if !reflect.DeepEqual(got, want) {
+		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,177 @@
+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()
+	sceneOwners := make(map[string]string)
+	for _, registered := range bot.plugins {
+		for name := range registered.scenes {
+			sceneOwners[name] = registered.name
+		}
+	}
+	for _, p := range plugin {
+		if p == nil {
+			if bot.logger != nil {
+				bot.logger.Warn("nil plugin skipped")
+			}
+			continue
+		}
+		cloned := clonePlugin(p)
+		for name := range cloned.scenes {
+			if owner, duplicate := sceneOwners[name]; duplicate {
+				if bot.logger != nil {
+					bot.logger.Warnf("scene %q from plugin %q duplicates plugin %q; skipping", name, cloned.name, owner)
+				}
+				delete(cloned.scenes, name)
+				continue
+			}
+			sceneOwners[name] = cloned.name
+		}
+		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

@@ -0,0 +1,838 @@
+package laniakea
+
+import (
+	"context"
+	"errors"
+	"io"
+	"net/http"
+	"os"
+	"path/filepath"
+	"reflect"
+	"strings"
+	"testing"
+	"time"
+
+	"git.scuroneko.dev/scuroneko/laniakea/tgapi"
+	"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[NoData]{updateTypes: []tgapi.UpdateType{tgapi.UpdateTypeMessage}}
+
+	got := bot.GetUpdateTypes()
+	got[0] = tgapi.UpdateTypeCallbackQuery
+
+	if want := []tgapi.UpdateType{tgapi.UpdateTypeMessage}; !reflect.DeepEqual(bot.updateTypes, want) {
+		t.Fatalf("GetUpdateTypes exposed internal slice: got %v want %v", bot.updateTypes, want)
+	}
+}
+
+func TestAddPluginsSnapshotsConfiguration(t *testing.T) {
+	bot := &Bot[NoData]{logger: sneklog.NewLogger()}
+	plugin := NewPlugin[NoData]("demo")
+
+	cmd := plugin.Command("start", func(ctx *MessageContext, db NoData) error { return nil })
+	plugin.AddMiddleware(NewMiddleware("base", func(ctx *MessageContext, db NoData) bool { return true }))
+
+	bot.AddPlugins(plugin)
+
+	cmd.SetDescription("mutated after registration")
+	plugin.Command("late", func(ctx *MessageContext, db NoData) error { return nil })
+	plugin.AddMiddleware(NewMiddleware("late", func(ctx *MessageContext, db NoData) bool { return true }))
+
+	registered := bot.plugins[0]
+	if _, exists := registered.commands["late"]; exists {
+		t.Fatal("late command leaked into registered plugin snapshot")
+	}
+	if registered.commands["start"].description != "" {
+		t.Fatalf("registered command description unexpectedly mutated: %q", registered.commands["start"].description)
+	}
+	if len(registered.middlewares) != 1 {
+		t.Fatalf("registered middlewares unexpectedly mutated: got %d want 1", len(registered.middlewares))
+	}
+}
+
+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[NoData]{logger: sneklog.NewLogger()}
+	plugin := NewPlugin[NoData]("demo")
+
+	bot.AddPlugins(nil, plugin)
+
+	if len(bot.plugins) != 1 {
+		t.Fatalf("expected exactly one registered plugin, got %d", len(bot.plugins))
+	}
+	if bot.plugins[0].name != "demo" {
+		t.Fatalf("unexpected plugin name: %q", bot.plugins[0].name)
+	}
+}
+
+func TestInitLoggersFallsBackToStdoutLoggerOnFileError(t *testing.T) {
+	bot := &Bot[NoData]{}
+
+	bot.initLoggers(&BotOpts{
+		Debug:            true,
+		WriteToFile:      true,
+		UseRequestLogger: true,
+		LoggerBasePath:   filepath.Join(t.TempDir(), "missing", "nested"),
+	})
+
+	if bot.logger == nil {
+		t.Fatal("expected main logger fallback")
+	}
+	if bot.requestLogger == nil {
+		t.Fatal("expected request logger fallback")
+	}
+	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)
+	}
+}
+
+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
+		prev time.Duration
+		want time.Duration
+	}{
+		{name: "initial", prev: 0, want: time.Second},
+		{name: "double", prev: 2 * time.Second, want: 4 * time.Second},
+		{name: "cap", prev: 20 * time.Second, want: 30 * time.Second},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			if got := nextPollRetryDelay(tt.prev); got != tt.want {
+				t.Fatalf("nextPollRetryDelay(%s) = %s, want %s", tt.prev, got, tt.want)
+			}
+		})
+	}
+}
+
+func TestAddDatabaseLoggerWriterSkipsWhenAppDataIsUnset(t *testing.T) {
+	bot := &Bot[NoData]{logger: sneklog.NewLogger()}
+	called := false
+
+	bot.AddAppDataLoggerWriter(func(db NoData) sneklog.LoggerWriter {
+		called = true
+		return nil
+	})
+
+	if called {
+		t.Fatal("expected app-data logger writer to be skipped when app data is unset")
+	}
+}
+
+func TestAddDatabaseLoggerWriterSkipsWhenAppDataIsNil(t *testing.T) {
+	type testDB struct{}
+
+	bot := &Bot[*testDB]{logger: sneklog.NewLogger()}
+	var db *testDB
+	bot.SetAppData(db)
+
+	called := false
+	bot.AddAppDataLoggerWriter(func(db *testDB) sneklog.LoggerWriter {
+		called = true
+		return nil
+	})
+
+	if called {
+		t.Fatal("expected app-data logger writer to be skipped when app data is nil")
+	}
+}
+
+func TestShouldWarnOnValueAppData(t *testing.T) {
+	type testDB struct{}
+	type dbIface interface{ Ping() error }
+
+	tests := []struct {
+		name string
+		got  bool
+		want bool
+	}{
+		{name: "NoData", got: shouldWarnOnValueAppData[NoData](), want: false},
+		{name: "pointer", got: shouldWarnOnValueAppData[*testDB](), want: false},
+		{name: "interface", got: shouldWarnOnValueAppData[dbIface](), want: false},
+		{name: "map", got: shouldWarnOnValueAppData[map[string]int](), want: false},
+		{name: "struct", got: shouldWarnOnValueAppData[testDB](), 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("shouldWarnOnValueAppData = %v, want %v", tt.got, tt.want)
+			}
+		})
+	}
+}
+
+func TestSetAppDataMarksValueWarningOnce(t *testing.T) {
+	type testDB struct{}
+
+	bot := &Bot[testDB]{logger: sneklog.NewLogger()}
+	bot.SetAppData(testDB{})
+	if !bot.warnedValueData {
+		t.Fatal("expected value-typed app data to mark warning state")
+	}
+
+	ptrBot := &Bot[*testDB]{logger: sneklog.NewLogger()}
+	ptrBot.SetAppData(&testDB{})
+	if ptrBot.warnedValueData {
+		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)
+	}
+}
+
+func TestRunWithContextRejectsSecondRun(t *testing.T) {
+	ctx, cancel := context.WithCancel(context.Background())
+	cancel()
+
+	bot := &Bot[NoData]{
+		logger:      sneklog.NewLogger(),
+		prefixes:    []string{"/"},
+		plugins:     []Plugin[NoData]{{name: "demo"}},
+		updateQueue: make(chan *tgapi.Update, 1),
+		maxWorkers:  1,
+	}
+
+	if err := bot.RunWithContext(ctx); err != nil {
+		t.Fatalf("first RunWithContext returned error: %v", err)
+	}
+	if err := bot.RunWithContext(ctx); !errors.Is(err, ErrBotAlreadyRun) {
+		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,475 @@
+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 := validateWebhookSecretToken(opts.SecretToken); err != nil {
+		return err
+	}
+	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("No webhook secret was configured; generated a random secret token")
+		}
+		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),
+		ReadHeaderTimeout: 5 * time.Second,
+		ReadTimeout:       10 * time.Second,
+		IdleTimeout:       60 * time.Second,
+	}
+	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 validateWebhookSecretToken(token string) error {
+	if len(token) < 1 || len(token) > 256 {
+		return ErrBotWebhookOptsSecretTokenInvalid
+	}
+	for _, r := range token {
+		if (r < 'A' || r > 'Z') &&
+			(r < 'a' || r > 'z') &&
+			(r < '0' || r > '9') &&
+			r != '_' && r != '-' {
+			return ErrBotWebhookOptsSecretTokenInvalid
+		}
+	}
+	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,396 @@
+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 TestValidateWebhookSecretToken(t *testing.T) {
+	tests := []struct {
+		name    string
+		token   string
+		wantErr bool
+	}{
+		{name: "minimum", token: "a"},
+		{name: "allowed alphabet", token: "AZaz09_-"},
+		{name: "maximum", token: strings.Repeat("a", 256)},
+		{name: "empty", token: "", wantErr: true},
+		{name: "too long", token: strings.Repeat("a", 257), wantErr: true},
+		{name: "padding", token: "abc=", wantErr: true},
+		{name: "non ASCII", token: "секрет", wantErr: true},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			err := validateWebhookSecretToken(tt.token)
+			if tt.wantErr && !errors.Is(err, ErrBotWebhookOptsSecretTokenInvalid) {
+				t.Fatalf("expected ErrBotWebhookOptsSecretTokenInvalid, got %v", err)
+			}
+			if !tt.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

@@ -1,68 +1,165 @@
 package laniakea
 
 import (
+	"context"
 	"errors"
 	"fmt"
+	"regexp"
+	"sort"
 	"strings"
 
-	"git.nix13.pw/scuroneko/laniakea/tgapi"
+	"git.scuroneko.dev/scuroneko/laniakea/tgapi"
 )
 
-func generateBotCommand[T any](cmd Command[T]) tgapi.BotCommand {
-	desc := cmd.command
+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.
+//
+// Telegram Bot API enforces this limit strictly. If exceeded, SetMyCommands
+// will fail with a 400 error. This error helps catch the issue early during
+// bot initialization.
+var ErrTooManyCommands = errors.New("too many commands. max 100")
+
+func generateBotCommand[T any](cmd *Command[T]) tgapi.BotCommand {
+	desc := ""
 	if len(cmd.description) > 0 {
 		desc = cmd.description
 	}
+
 	var descArgs []string
 	for _, a := range cmd.args {
 		if a.required {
-			descArgs = append(descArgs, fmt.Sprintf("%s", a.text))
+			descArgs = append(descArgs, fmt.Sprintf("<%s>", a.text))
 		} else {
 			descArgs = append(descArgs, fmt.Sprintf("[%s]", a.text))
 		}
 	}
-	desc = fmt.Sprintf("%s. Usage: /%s %s", desc, cmd.command, strings.Join(descArgs, " "))
-	return tgapi.BotCommand{Command: cmd.command, Description: desc}
+
+	usage := fmt.Sprintf("Usage: /%s %s", cmd.command, strings.Join(descArgs, " "))
+	if desc != "" {
+		desc = fmt.Sprintf("%s. %s", desc, usage)
+		return tgapi.BotCommand{Command: cmd.command, Description: desc, IsEphemeral: cmd.isEphemeral}
+	}
+	return tgapi.BotCommand{Command: cmd.command, Description: usage, IsEphemeral: cmd.isEphemeral}
 }
 
-func generateBotCommandForPlugin[T any](pl Plugin[T]) []tgapi.BotCommand {
+func checkCmdRegex(cmd string) bool { return cmdRegexp.MatchString(cmd) }
+
+func gatherCommandsForPlugin[T any](pl Plugin[T]) []tgapi.BotCommand {
 	commands := make([]tgapi.BotCommand, 0)
-	for _, cmd := range pl.Commands {
+	names := make([]string, 0, len(pl.commands))
+	for name := range pl.commands {
+		names = append(names, name)
+	}
+	sort.Strings(names)
+
+	for _, name := range names {
+		cmd := pl.commands[name]
 		if cmd.skipAutoCmd {
 			continue
 		}
+		if !checkCmdRegex(cmd.command) {
+			continue
+		}
 		commands = append(commands, generateBotCommand(cmd))
 	}
 	return commands
 }
 
-var ErrTooManyCommands = errors.New("too many commands. max 100")
-
-func (bot *Bot[T]) AutoGenerateCommands() error {
-	_, err := bot.api.DeleteMyCommands(tgapi.DeleteMyCommandsP{})
-	if err != nil {
-		return err
-	}
-
+func gatherCommands[T any](bot *Bot[T]) []tgapi.BotCommand {
 	commands := make([]tgapi.BotCommand, 0)
 	for _, pl := range bot.plugins {
-		commands = append(commands, generateBotCommandForPlugin(pl)...)
+		if pl.skipAutoCmd {
+			continue
+		}
+		commands = append(commands, gatherCommandsForPlugin(pl)...)
+		bot.logger.Debugln(fmt.Sprintf("Registered %d commands from plugin %s", len(pl.commands), pl.name))
 	}
+	return commands
+}
+
+// AutoGenerateCommands replaces plugin-defined commands in the private-chat,
+// group-chat, and all-chat-administrators scopes.
+//
+// Returns ErrTooManyCommands if the total number of commands exceeds 100.
+// Returns any API error from Telegram (e.g., network issues, invalid scope).
+//
+// Important: This method assumes the bot has been properly initialized and
+// the API client is authenticated and ready.
+//
+// Usage:
+//
+//	err := bot.AutoGenerateCommands()
+//	if err != nil {
+//	    log.Fatal(err)
+//	}
+func (bot *Bot[T]) AutoGenerateCommands() error {
+	return bot.AutoGenerateCommandsWithContext(context.Background())
+}
+
+// AutoGenerateCommandsWithContext is the context-aware variant of AutoGenerateCommands.
+func (bot *Bot[T]) AutoGenerateCommandsWithContext(ctx context.Context) error {
+	commands := gatherCommands(bot)
 	if len(commands) > 100 {
 		return ErrTooManyCommands
 	}
 
-	privateChatsScope := &tgapi.BotCommandScope{Type: tgapi.BotCommandScopePrivateType}
-	groupChatsScope := &tgapi.BotCommandScope{Type: tgapi.BotCommandScopeGroupType}
-	chatAdminsScope := &tgapi.BotCommandScope{Type: tgapi.BotCommandScopeAllChatAdministratorsType}
-	_, err = bot.api.SetMyCommands(tgapi.SetMyCommandsP{Commands: commands, Scope: privateChatsScope})
-	if err != nil {
-		return err
+	// Register commands for each scope
+	scopes := []tgapi.BotCommandScope{
+		{Type: tgapi.BotCommandScopePrivateType},
+		{Type: tgapi.BotCommandScopeGroupType},
+		{Type: tgapi.BotCommandScopeAllChatAdministratorsType},
 	}
-	_, err = bot.api.SetMyCommands(tgapi.SetMyCommandsP{Commands: commands, Scope: groupChatsScope})
-	if err != nil {
-		return err
+
+	for i := range scopes {
+		if err := bot.setCommandsForScope(ctx, &scopes[i], commands); err != nil {
+			return err
+		}
 	}
-	_, err = bot.api.SetMyCommands(tgapi.SetMyCommandsP{Commands: commands, Scope: chatAdminsScope})
-	return err
+	return nil
+}
+
+// AutoGenerateCommandsForScope registers all plugin-defined commands with Telegram's Bot API
+// for the specified command scope. A nil scope selects Telegram's default scope.
+//
+// The scope parameter defines where the commands should be available (e.g., private chats,
+// group chats, chat administrators). See tgapi.BotCommandScope and its predefined types.
+//
+// Returns ErrTooManyCommands if the total number of commands exceeds 100.
+// Returns any API error from Telegram (e.g., network issues, invalid scope).
+//
+// Usage:
+//
+//	privateScope := &tgapi.BotCommandScope{Type: tgapi.BotCommandScopePrivateType}
+//	if err := bot.AutoGenerateCommandsForScope(privateScope); err != nil {
+//	    log.Fatal(err)
+//	}
+func (bot *Bot[T]) AutoGenerateCommandsForScope(scope *tgapi.BotCommandScope) error {
+	return bot.AutoGenerateCommandsForScopeWithContext(context.Background(), scope)
+}
+
+// AutoGenerateCommandsForScopeWithContext is the context-aware variant of
+// AutoGenerateCommandsForScope.
+func (bot *Bot[T]) AutoGenerateCommandsForScopeWithContext(ctx context.Context, scope *tgapi.BotCommandScope) error {
+	commands := gatherCommands(bot)
+	if len(commands) > 100 {
+		return ErrTooManyCommands
+	}
+	return bot.setCommandsForScope(ctx, scope, commands)
+}
+
+func (bot *Bot[T]) setCommandsForScope(ctx context.Context, scope *tgapi.BotCommandScope, commands []tgapi.BotCommand) error {
+	if len(commands) > 100 {
+		return ErrTooManyCommands
+	}
+	_, err := bot.api.SetMyCommandsWithContext(ctx, tgapi.SetMyCommands{Scope: scope, Commands: commands})
+	if err != nil {
+		scopeType := tgapi.BotCommandScopeDefaultType
+		if scope != nil {
+			scopeType = scope.Type
+		}
+		return fmt.Errorf("failed to set commands for scope %q: %w", scopeType, err)
+	}
+	return nil
 }

cmd_generator_test.go

@@ -0,0 +1,132 @@
+package laniakea
+
+import (
+	"errors"
+	"io"
+	"net/http"
+	"reflect"
+	"strconv"
+	"strings"
+	"sync/atomic"
+	"testing"
+
+	"git.scuroneko.dev/scuroneko/laniakea/tgapi"
+	"git.scuroneko.dev/scuroneko/sneklog/v2"
+)
+
+type roundTripFunc func(*http.Request) (*http.Response, error)
+
+func (fn roundTripFunc) RoundTrip(req *http.Request) (*http.Response, error) {
+	return fn(req)
+}
+
+func TestAutoGenerateCommandsChecksLimitBeforeDelete(t *testing.T) {
+	var calls atomic.Int64
+	client := &http.Client{
+		Transport: roundTripFunc(func(req *http.Request) (*http.Response, error) {
+			calls.Add(1)
+			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)
+		}
+	}()
+
+	plugin := NewPlugin[NoData]("overflow")
+	exec := func(ctx *MessageContext, db NoData) error { return nil }
+	for i := 0; i < 101; i++ {
+		plugin.Command("cmd"+strconv.Itoa(i), exec)
+	}
+
+	bot := &Bot[NoData]{
+		api:     api,
+		logger:  sneklog.NewLogger(),
+		plugins: []Plugin[NoData]{*plugin},
+	}
+
+	err := bot.AutoGenerateCommands()
+	if !errors.Is(err, ErrTooManyCommands) {
+		t.Fatalf("expected ErrTooManyCommands, got %v", err)
+	}
+	if calls.Load() != 0 {
+		t.Fatalf("expected no HTTP calls before limit validation, got %d", calls.Load())
+	}
+}
+
+func TestGatherCommandsForPluginReturnsSortedCommands(t *testing.T) {
+	plugin := NewPlugin[NoData]("sorted")
+	exec := func(ctx *MessageContext, db NoData) error { return nil }
+
+	plugin.Command("zeta", exec)
+	plugin.Command("alpha", exec)
+	plugin.Command("mid", exec)
+
+	commands := gatherCommandsForPlugin(*plugin)
+	got := make([]string, 0, len(commands))
+	for _, cmd := range commands {
+		got = append(got, cmd.Command)
+	}
+
+	want := []string{"alpha", "mid", "zeta"}
+	if !reflect.DeepEqual(got, want) {
+		t.Fatalf("unexpected command order: got %v want %v", got, want)
+	}
+}
+
+func TestAutoGenerateCommandsForNilScopeUsesSingleAtomicReplacement(t *testing.T) {
+	var methods []string
+	client := &http.Client{
+		Transport: roundTripFunc(func(req *http.Request) (*http.Response, error) {
+			methods = append(methods, req.URL.Path)
+			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)
+		}
+	}()
+
+	plugin := NewPlugin[NoData]("commands")
+	plugin.Command("start", func(ctx *MessageContext, db NoData) error { return nil })
+	bot := &Bot[NoData]{
+		api:     api,
+		logger:  sneklog.NewLogger(),
+		plugins: []Plugin[NoData]{*plugin},
+	}
+	defer func() {
+		if err := bot.logger.Close(); err != nil {
+			t.Fatalf("Close logger returned error: %v", err)
+		}
+	}()
+
+	if err := bot.AutoGenerateCommandsForScope(nil); err != nil {
+		t.Fatalf("AutoGenerateCommandsForScope returned error: %v", err)
+	}
+	if len(methods) != 1 {
+		t.Fatalf("expected one request, got %d", len(methods))
+	}
+	if !strings.HasSuffix(methods[0], "/setMyCommands") {
+		t.Fatalf("expected setMyCommands request, got %v", methods[0])
+	}
+}

commands.go

@@ -0,0 +1,225 @@
+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
+	isEphemeral bool
+}
+
+// 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, 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
+}
+
+// SetEphemeral controls whether Telegram treats the command as ephemeral.
+//
+// Since: Bot API 10.2
+func (c *Command[T]) SetEphemeral(b bool) *Command[T] {
+	c.isEphemeral = b
+	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

@@ -0,0 +1,33 @@
+/*
+Package laniakea provides a modular, extensible framework for building scalable Telegram bots.
+
+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.
+  - 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.
+  - Runners execute startup or background tasks alongside the polling loop.
+
+Example usage:
+
+	bot, err := laniakea.NewBot[*mydb.AppData](laniakea.LoadOptsFromEnv())
+	if err != nil {
+	    return err
+	}
+	bot.SetAppData(myDB).
+	    AddUpdateType(tgapi.UpdateTypeMessage).
+	    AddPrefixes("/", "!").
+	    AddPlugins(&startPlugin, &helpPlugin).
+	    AddMiddleware(authMiddleware, logMiddleware).
+	    AddRunner(cleanupRunner).
+	    SetL10n(l10n.New())
+
+	return bot.Run()
+
+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

@@ -0,0 +1,282 @@
+package laniakea
+
+import (
+	"math/rand/v2"
+	"sync"
+	"sync/atomic"
+
+	"git.scuroneko.dev/scuroneko/laniakea/tgapi"
+)
+
+type draftIDGenerator interface {
+	Next() uint64
+}
+
+// RandomDraftIDGenerator generates draft IDs using math/rand/v2.
+//
+// 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 {
+	return rand.Uint64()
+}
+
+// LinearDraftIDGenerator generates draft IDs using a monotonically increasing counter.
+// Useful for debugging, persistence, or when drafts must be ordered.
+type LinearDraftIDGenerator struct {
+	lastID atomic.Uint64
+}
+
+// Next returns the next linear ID, atomically incremented.
+func (g *LinearDraftIDGenerator) Next() uint64 {
+	return g.lastID.Add(1)
+}
+
+// DraftProvider manages a collection of Drafts and a shared draft ID generator.
+//
+// DraftProvider is safe for concurrent use.
+type DraftProvider struct {
+	mu        sync.RWMutex
+	api       *tgapi.API
+	drafts    map[uint64]*Draft
+	generator draftIDGenerator
+}
+
+// NewRandomDraftProvider creates a new DraftProvider using random 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{},
+		drafts: make(map[uint64]*Draft),
+	}
+}
+
+// NewLinearDraftProvider creates a new DraftProvider using linear (incrementing) draft IDs.
+//
+// startValue is the initial value for the counter. Use 0 for fresh start, or a known
+// value to resume from persisted state.
+//
+// This is useful when you need to store draft IDs externally (e.g., in a database)
+// and want to reconstruct drafts after restart.
+func NewLinearDraftProvider(api *tgapi.API, startValue uint64) *DraftProvider {
+	g := &LinearDraftIDGenerator{}
+	g.lastID.Store(startValue)
+	return &DraftProvider{
+		api:       api,
+		generator: g,
+		drafts:    make(map[uint64]*Draft),
+	}
+}
+
+// GetDraft retrieves a draft by its ID.
+//
+// Returns the draft and true if found, or nil and false if not found.
+func (p *DraftProvider) GetDraft(id uint64) (*Draft, bool) {
+	p.mu.RLock()
+	defer p.mu.RUnlock()
+	draft, ok := p.drafts[id]
+	return draft, ok
+}
+
+// FlushAll sends all pending drafts as final messages and clears them.
+//
+// If one or more drafts fail to send, FlushAll still attempts all drafts and
+// returns the first encountered error.
+//
+// After successful flush, each draft is removed from the provider and cleared.
+func (p *DraftProvider) FlushAll() error {
+	p.mu.RLock()
+	drafts := make([]*Draft, 0, len(p.drafts))
+	for _, draft := range p.drafts {
+		drafts = append(drafts, draft)
+	}
+	p.mu.RUnlock()
+
+	var firstErr error
+	for _, draft := range drafts {
+		if err := draft.Flush(); err != nil && firstErr == nil {
+			firstErr = err
+		}
+	}
+	return firstErr
+}
+
+// Draft represents a single message draft that can be edited and flushed.
+//
+// Drafts are safe to use from a single goroutine. Multiple goroutines must
+// synchronize access manually.
+//
+// Drafts are automatically removed from the provider's map when Flush() succeeds.
+type Draft struct {
+	api      *tgapi.API
+	provider *DraftProvider
+
+	chatID          int64
+	messageThreadID int
+	parseMode       tgapi.ParseMode
+	entities        []tgapi.MessageEntity
+
+	ID      uint64
+	Message string
+}
+
+// NewDraft creates a new draft with the provided parse mode.
+//
+// The caller must set a chat with SetChat before Push or Flush.
+func (p *DraftProvider) NewDraft(parseMode tgapi.ParseMode) *Draft {
+	p.mu.Lock()
+	defer p.mu.Unlock()
+
+	var id uint64
+	for {
+		id = p.generator.Next()
+		if id == 0 {
+			continue
+		}
+		if _, exists := p.drafts[id]; !exists {
+			break
+		}
+	}
+	draft := &Draft{
+		api:       p.api,
+		provider:  p,
+		parseMode: parseMode,
+		ID:        id,
+		Message:   "",
+	}
+	p.drafts[id] = draft
+	return draft
+}
+
+// SetChat overrides the draft's target chat and message thread.
+//
+// This is useful for sending a draft to a different chat than the provider's default.
+func (d *Draft) SetChat(chatID int64, messageThreadID int) *Draft {
+	d.chatID = chatID
+	d.messageThreadID = messageThreadID
+	return d
+}
+
+// SetEntities replaces the draft's message entities.
+//
+// The entities slice is copied.
+func (d *Draft) SetEntities(entities []tgapi.MessageEntity) *Draft {
+	d.entities = append([]tgapi.MessageEntity(nil), entities...)
+	return d
+}
+
+// Push appends text to the draft and attempts to update the server-side draft.
+//
+// Returns an error if the Telegram API rejects the update (e.g., due to network issues).
+// The draft's Message field is always updated, even if the API call fails.
+//
+// Use this method to build the message incrementally.
+func (d *Draft) Push(text string) error {
+	return d.push(text)
+}
+
+// GetMessage returns the current content of the draft.
+//
+// Useful for inspection, logging, or validation before flushing.
+func (d *Draft) GetMessage() string {
+	return d.Message
+}
+
+// Clear resets the draft's message content to empty string.
+//
+// Does not affect server-side draft — use Flush() for that.
+func (d *Draft) Clear() {
+	d.Message = ""
+}
+
+// Delete removes the draft from its provider and clears its content.
+//
+// You may call it manually if you want to cancel a draft without sending it.
+func (d *Draft) Delete() {
+	if d.provider != nil {
+		d.provider.mu.Lock()
+		delete(d.provider.drafts, d.ID)
+		d.provider.mu.Unlock()
+	}
+	d.Clear()
+}
+
+// Flush sends the draft as a final message and clears it locally.
+//
+// If successful:
+//   - The message is sent to Telegram.
+//   - The draft's content is cleared.
+//   - The draft is removed from the provider's map.
+//
+// If an error occurs:
+//   - The message is NOT sent.
+//   - The draft remains in the provider and retains its content.
+//   - You can call Flush() again to retry.
+//
+// If the draft is empty, Flush() returns nil without calling the API.
+func (d *Draft) Flush() error {
+	if d.Message == "" {
+		return nil
+	}
+	if d.chatID == 0 {
+		return ErrDraftChatIDZero
+	}
+	if err := validateMessageText(d.Message); err != nil {
+		return err
+	}
+	if d.api == nil {
+		return ErrAPIIsNil
+	}
+
+	params := tgapi.SendMessage{
+		ChatID:    d.chatID,
+		ParseMode: d.parseMode,
+		Entities:  d.entities,
+		Text:      d.Message,
+	}
+	if d.messageThreadID > 0 {
+		params.MessageThreadID = d.messageThreadID
+	}
+
+	_, err := d.api.SendMessage(params)
+	if err == nil {
+		d.Delete()
+	}
+	return err
+}
+
+// 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
+	}
+	candidate := d.Message + text
+	if err := validateMessageText(candidate); err != nil {
+		return err
+	}
+	d.Message = candidate
+	if d.api == nil {
+		return ErrAPIIsNil
+	}
+	params := tgapi.SendMessageDraft{
+		ChatID:    d.chatID,
+		DraftID:   d.ID,
+		Text:      d.Message,
+		ParseMode: d.parseMode,
+		Entities:  d.entities,
+	}
+	if d.messageThreadID > 0 {
+		params.MessageThreadID = d.messageThreadID
+	}
+	_, err := d.api.SendMessageDraft(params)
+	return err
+}

drafts_test.go

@@ -0,0 +1,112 @@
+package laniakea
+
+import (
+	"errors"
+	"strings"
+	"testing"
+
+	"git.scuroneko.dev/scuroneko/laniakea/tgapi"
+	"git.scuroneko.dev/scuroneko/sneklog/v2"
+)
+
+type sequenceDraftIDGenerator struct {
+	ids []uint64
+	pos int
+}
+
+func (g *sequenceDraftIDGenerator) Next() uint64 {
+	id := g.ids[g.pos]
+	g.pos++
+	return id
+}
+
+func TestDraftFlushRequiresChatID(t *testing.T) {
+	draft := NewRandomDraftProvider(&tgapi.API{}).NewDraft(tgapi.ParseNone)
+	draft.Message = "hello"
+
+	if err := draft.Flush(); !errors.Is(err, ErrDraftChatIDZero) {
+		t.Fatalf("expected ErrDraftChatIDZero, got %v", err)
+	}
+}
+
+func TestMsgContextNewDraftWorksWithoutLimiter(t *testing.T) {
+	ctx := &MessageContext{
+		API: &tgapi.API{},
+		Msg: &tgapi.Message{
+			Chat: &tgapi.Chat{ID: 42, Type: tgapi.ChatTypePrivate},
+		},
+		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 TestDraftProviderSkipsZeroAndCollidingIDs(t *testing.T) {
+	provider := &DraftProvider{
+		api:       &tgapi.API{},
+		drafts:    make(map[uint64]*Draft),
+		generator: &sequenceDraftIDGenerator{ids: []uint64{0, 7, 7, 8}},
+	}
+
+	first := provider.NewDraft(tgapi.ParseNone)
+	second := provider.NewDraft(tgapi.ParseNone)
+	if first.ID != 7 || second.ID != 8 {
+		t.Fatalf("unexpected draft IDs: first=%d second=%d", first.ID, second.ID)
+	}
+	if got := len(provider.drafts); got != 2 {
+		t.Fatalf("collision overwrote a draft: got %d drafts", got)
+	}
+}
+
+func TestDraftReturnsErrorWhenAPIIsNil(t *testing.T) {
+	draft := NewLinearDraftProvider(nil, 0).NewDraft(tgapi.ParseNone).SetChat(42, 0)
+	if err := draft.Push("hello"); !errors.Is(err, ErrAPIIsNil) {
+		t.Fatalf("expected ErrAPIIsNil from Push, got %v", err)
+	}
+	draft.Message = "hello"
+	if err := draft.Flush(); !errors.Is(err, ErrAPIIsNil) {
+		t.Fatalf("expected ErrAPIIsNil from Flush, got %v", err)
+	}
+}
+
+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,61 @@
+package laniakea
+
+import "errors"
+
+type classifiedError struct {
+	err          error
+	userVisible  bool
+	internalOnly bool
+}
+
+// Error returns the underlying error message.
+func (e *classifiedError) Error() string {
+	if e == nil || e.err == nil {
+		return ""
+	}
+	return e.err.Error()
+}
+
+// Unwrap returns the underlying 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,114 @@
+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")
+	// ErrBotWebhookOptsSecretTokenInvalid reports that SecretToken violates Telegram's format.
+	ErrBotWebhookOptsSecretTokenInvalid = errors.New("BotWebhookOpts.SecretToken must be 1-256 characters from A-Z, a-z, 0-9, _ and -")
+	// 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,15 +1,12 @@
-module git.nix13.pw/scuroneko/laniakea
+module git.scuroneko.dev/scuroneko/laniakea
 
 go 1.26
 
-require (
-	git.nix13.pw/scuroneko/extypes v1.2.0
-	git.nix13.pw/scuroneko/slog v1.0.2
-)
+retract v1.0.0-rc.5
 
 require (
-	github.com/fatih/color v1.18.0 // indirect
-	github.com/mattn/go-colorable v0.1.14 // indirect
-	github.com/mattn/go-isatty v0.0.20 // indirect
-	golang.org/x/sys v0.41.0 // indirect
+	git.scuroneko.dev/scuroneko/extypes v1.2.3
+	git.scuroneko.dev/scuroneko/sneklog/v2 v2.3.0
+	github.com/alitto/pond/v2 v2.7.1
+	golang.org/x/time v0.15.0
 )

go.sum

@@ -1,13 +1,8 @@
-git.nix13.pw/scuroneko/extypes v1.2.0 h1:2n2hD6KsMAted+6MGhAyeWyli2Qzc9G2y+pQNB7C1dM=
-git.nix13.pw/scuroneko/extypes v1.2.0/go.mod h1:uZVs8Yo3RrYAG9dMad6qR6lsYY67t+459D9c65QAYAw=
-git.nix13.pw/scuroneko/slog v1.0.2 h1:vZyUROygxC2d5FJHUQM/30xFEHY1JT/aweDZXA4rm2g=
-git.nix13.pw/scuroneko/slog v1.0.2/go.mod h1:3Qm2wzkR5KjwOponMfG7TcGSDjmYaFqRAmLvSPTuWJI=
-github.com/fatih/color v1.18.0 h1:S8gINlzdQ840/4pfAwic/ZE0djQEH3wM94VfqLTZcOM=
-github.com/fatih/color v1.18.0/go.mod h1:4FelSpRwEGDpQ12mAdzqdOukCy4u8WUtOY6lkT/6HfU=
-github.com/mattn/go-colorable v0.1.14 h1:9A9LHSqF/7dyVVX6g0U9cwm9pG3kP9gSzcuIPHPsaIE=
-github.com/mattn/go-colorable v0.1.14/go.mod h1:6LmQG8QLFO4G5z1gPvYEzlUgJ2wF+stgPZH1UqBm1s8=
-github.com/mattn/go-isatty v0.0.20 h1:xfD0iDuEKnDkl03q4limB+vH+GxLEtL/jb4xVJSWWEY=
-github.com/mattn/go-isatty v0.0.20/go.mod h1:W+V8PltTTMOvKvAeJH7IuucS94S2C6jfK/D7dTCTo3Y=
-golang.org/x/sys v0.6.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
-golang.org/x/sys v0.41.0 h1:Ivj+2Cp/ylzLiEU89QhWblYnOE9zerudt9Ftecq2C6k=
-golang.org/x/sys v0.41.0/go.mod h1:OgkHotnGiDImocRcuBABYBEXf8A9a87e/uXjp9XT3ks=
+git.scuroneko.dev/scuroneko/extypes v1.2.3 h1:n7QsfTZEn9fJNZLXGH/LkNq4cADaRk+LTu6LNMv9y6s=
+git.scuroneko.dev/scuroneko/extypes v1.2.3/go.mod h1:MhYpXC6sloLOpoM2guf64eSOrz+ET/QJZ8toobc3Ors=
+git.scuroneko.dev/scuroneko/sneklog/v2 v2.3.0 h1:gaPe5azwuDTh48jRB/P2FUgOs7f1ToNr0S+NBizKvY8=
+git.scuroneko.dev/scuroneko/sneklog/v2 v2.3.0/go.mod h1:q8XnLXzLdGjW0Jtcbh9/+G9WmfD68rsPQvLXEPxvum4=
+github.com/alitto/pond/v2 v2.7.1 h1:QxMbcfjcVTa0pyxX5Ib1226mM8u8D7gKUVkCUU4DYIw=
+github.com/alitto/pond/v2 v2.7.1/go.mod h1:xkjYEgQ05RSpWdfSd1nM3OVv7TBhLdy7rMp3+2Nq+yE=
+golang.org/x/time v0.15.0 h1:bbrp8t3bGUeFOx08pvsMYRTCVSMk89u4tKbNOZbp88U=
+golang.org/x/time v0.15.0/go.mod h1:Y4YMaQmXwGQZoFaVFk4YpCt4FLQMYKZe9oeV/f4MSno=

handler.go

@@ -1,148 +1,331 @@
 package laniakea
 
 import (
+	"context"
 	"encoding/base64"
 	"encoding/json"
+	"errors"
+	"fmt"
 	"strings"
+	"time"
 
-	"git.nix13.pw/scuroneko/laniakea/tgapi"
+	"git.scuroneko.dev/scuroneko/laniakea/tgapi"
 )
 
-func (bot *Bot[T]) handle(u *tgapi.Update) {
-	ctx := &MsgContext{Update: *u, Api: bot.api, botLogger: bot.logger, errorTemplate: bot.errorTemplate, l10n: bot.l10n}
+// ErrInvalidPayloadType is returned when callback payload encoding type is unknown.
+var ErrInvalidPayloadType = errors.New("invalid payload type")
+
+// 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 {
+			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, cancel := context.WithCancel(parentCtx)
+	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, msgCtx)
+	unlockScenes := bot.sceneLocks.lock(sceneKeysForContext(msgCtx))
+	defer unlockScenes()
+	bot.safeEmitEvent(ctx, UpdateReceivedEvent{
+		UpdateID:   u.UpdateID,
+		UpdateType: u.Type,
+		FromID:     msgCtx.FromID,
+		ChatID:     msgCtx.ChatID,
+	})
+
 	for _, middleware := range bot.middlewares {
-		middleware.Execute(ctx, bot.dbContext)
-	}
-
-	if u.CallbackQuery != nil {
-		bot.handleCallback(u, ctx)
-	} else {
-		bot.handleMessage(u, ctx)
-	}
-}
-
-func (bot *Bot[T]) handleMessage(update *tgapi.Update, ctx *MsgContext) {
-	if update.Message == nil {
-		return
-	}
-
-	var text string
-	if len(update.Message.Text) > 0 {
-		text = update.Message.Text
-	} else {
-		text = update.Message.Caption
-	}
-
-	text = strings.TrimSpace(text)
-	prefix, hasPrefix := bot.checkPrefixes(text)
-	if !hasPrefix {
-		return
-	}
-	ctx.Prefix = prefix
-	ctx.FromID = update.Message.From.ID
-	ctx.From = update.Message.From
-	ctx.Msg = update.Message
-
-	text = strings.TrimSpace(text[len(prefix):])
-
-	for _, plugin := range bot.plugins {
-		for cmd := range plugin.Commands {
-			if !strings.HasPrefix(text, cmd) {
-				continue
-			}
-			requestParts := strings.Split(text, " ")
-			cmdParts := strings.Split(cmd, " ")
-			isValid := true
-			for i, part := range cmdParts {
-				if part != requestParts[i] {
-					isValid = false
-					break
-				}
-			}
-
-			if !isValid {
-				continue
-			}
-
-			ctx.Text = strings.TrimSpace(text[len(cmd):])
-			if ctx.Text == "" {
-				ctx.Args = []string{}
-			} else {
-				ctx.Args = strings.Split(ctx.Text, " ")
-			}
-
-			if !plugin.executeMiddlewares(ctx, bot.dbContext) {
-				return
-			}
-			go plugin.executeCmd(cmd, 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
 		}
 	}
-}
 
-func (bot *Bot[T]) handleCallback(update *tgapi.Update, ctx *MsgContext) {
-	data := new(CallbackData)
-	err := json.Unmarshal([]byte(update.CallbackQuery.Data), data)
+	sceneHandled, err := bot.tryHandleScene(msgCtx)
 	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.FromID = update.CallbackQuery.From.ID
-	ctx.From = &update.CallbackQuery.From
-	ctx.Msg = &update.CallbackQuery.Message
-	ctx.CallbackMsgId = update.CallbackQuery.Message.MessageID
-	ctx.CallbackQueryId = update.CallbackQuery.ID
-	ctx.Args = data.Args
-
-	for _, plugin := range bot.plugins {
-		_, ok := plugin.Payloads[data.Command]
-		if !ok {
-			continue
-		}
-
-		if !plugin.executeMiddlewares(ctx, bot.dbContext) {
-			return
-		}
-		go plugin.executePayload(data.Command, ctx, bot.dbContext)
-		return
+	handled := false
+	switch u.Type {
+	case tgapi.UpdateTypeMessage, tgapi.UpdateTypeChannelPost:
+		handled = bot.handleMessage(u, msgCtx)
+	case tgapi.UpdateTypeCallbackQuery:
+		handled = bot.handleCallback(u, msgCtx)
+	default:
+		handled = bot.handleUpdate(u, msgCtx)
 	}
+	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]) checkPrefixes(text string) (string, bool) {
-	for _, prefix := range bot.prefixes {
-		if strings.HasPrefix(text, prefix) {
-			return prefix, true
-		}
+func cloneMsgContext(src *MessageContext) *MessageContext {
+	cloned := *src
+	if src.Args != nil {
+		cloned.Args = append([]string(nil), src.Args...)
 	}
-	return "", false
+	return &cloned
 }
 
-func encodeJsonPayload(d CallbackData) (string, error) {
+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
 	}
-	dst := make([]byte, base64.StdEncoding.EncodedLen(len([]byte(data))))
-	base64.StdEncoding.Encode(dst, []byte(data))
+	dst := make([]byte, base64.RawURLEncoding.EncodedLen(len([]byte(data))))
+	base64.RawURLEncoding.Encode(dst, []byte(data))
 	return string(dst), nil
 }
+
 func decodeBase64Payload(s string) (CallbackData, error) {
-	b, err := base64.StdEncoding.DecodeString(s)
+	b, err := base64.RawURLEncoding.DecodeString(s)
 	if err != nil {
 		return CallbackData{}, err
 	}
-	return decodeJsonPayload(string(b))
+	return decodeJSONPayload(string(b))
+}
+
+// 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:
+		return decodeJSONPayload(s)
+	case BotPayloadCompact:
+		return decodeCompactPayload(s)
+	case BotPayloadCompactBase64:
+		return decodeCompactBase64Payload(s)
+	}
+	return CallbackData{}, ErrInvalidPayloadType
+}
+
+func decodePayload(payloadType BotPayloadType, s string, strict bool) (CallbackData, BotPayloadType, error) {
+	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) {
+	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

@@ -1,71 +1,217 @@
 package laniakea
 
 import (
-	"encoding/json"
 	"fmt"
 
-	"git.nix13.pw/scuroneko/extypes"
-	"git.nix13.pw/scuroneko/laniakea/tgapi"
+	"git.scuroneko.dev/scuroneko/extypes"
+	"git.scuroneko.dev/scuroneko/laniakea/tgapi"
 )
 
 const (
-	ButtonStyleDanger  tgapi.KeyboardButtonStyle = "danger"
+	// ButtonStyleDanger marks a destructive inline keyboard action.
+	ButtonStyleDanger tgapi.KeyboardButtonStyle = "danger"
+	// ButtonStyleSuccess marks a confirmatory inline keyboard action.
 	ButtonStyleSuccess tgapi.KeyboardButtonStyle = "success"
+	// ButtonStylePrimary marks a primary inline keyboard action.
 	ButtonStylePrimary tgapi.KeyboardButtonStyle = "primary"
 )
 
-type InlineKbButtonBuilder struct {
-	text              string
-	iconCustomEmojiID string
-	style             tgapi.KeyboardButtonStyle
-	url               string
-	callbackData      string
+// InlineKeyboardButtonBuilder is a fluent builder for creating a single inline keyboard button.
+//
+// Use NewInlineKeyboardButton() to start, then chain methods to configure:
+//   - SetIconCustomEmojiID() — adds a custom emoji icon
+//   - SetStyle() — sets visual style (danger/success/primary)
+//   - SetURL() — makes button open a URL
+//   - 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 InlineKeyboardButtonBuilder struct {
+	text    string
+	emojiID string
+	style   tgapi.KeyboardButtonStyle
+
+	url  string
+	data string
+
+	payloadType BotPayloadType
 }
 
-func NewInlineKbButton(text string) InlineKbButtonBuilder {
-	return InlineKbButtonBuilder{text: 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 NewInlineKeyboardButton(text string) InlineKeyboardButtonBuilder {
+	return InlineKeyboardButtonBuilder{text: text}
 }
-func (b InlineKbButtonBuilder) SetIconCustomEmojiId(id string) InlineKbButtonBuilder {
-	b.iconCustomEmojiID = id
+
+// 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 InlineKeyboardButtonBuilder) SetIconCustomEmojiID(id string) InlineKeyboardButtonBuilder {
+	b.emojiID = id
 	return b
 }
-func (b InlineKbButtonBuilder) SetStyle(style tgapi.KeyboardButtonStyle) InlineKbButtonBuilder {
+
+// SetStyle sets the visual style of the button.
+// Valid values: ButtonStyleDanger, ButtonStyleSuccess, ButtonStylePrimary.
+// If not set, the button uses the default style.
+func (b InlineKeyboardButtonBuilder) SetStyle(style tgapi.KeyboardButtonStyle) InlineKeyboardButtonBuilder {
 	b.style = style
 	return b
 }
-func (b InlineKbButtonBuilder) SetUrl(url string) InlineKbButtonBuilder {
+
+// SetURL sets a URL that will be opened when the button is pressed.
+// It clears callback data because Telegram requires exactly one button action.
+func (b InlineKeyboardButtonBuilder) SetURL(url string) InlineKeyboardButtonBuilder {
 	b.url = url
-	return b
-}
-func (b InlineKbButtonBuilder) SetCallbackData(cmd string, args ...any) InlineKbButtonBuilder {
-	b.callbackData = NewCallbackData(cmd, args...).ToJson()
+	if url != "" {
+		b.data = ""
+	}
 	return b
 }
 
-func (b InlineKbButtonBuilder) build() tgapi.InlineKeyboardButton {
+// 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"]}.
+func (b InlineKeyboardButtonBuilder) SetCallbackDataJSON(cmd string, args ...any) InlineKeyboardButtonBuilder {
+	b.url = ""
+	b.data = NewCallbackData(cmd, args...).ToJSON()
+	return b
+}
+
+// SetCallbackDataBase64 sets a Base64-encoded structured callback payload.
+// Base64 does not bypass Telegram's 64-byte callback-data limit.
+func (b InlineKeyboardButtonBuilder) SetCallbackDataBase64(cmd string, args ...any) InlineKeyboardButtonBuilder {
+	b.url = ""
+	b.data = NewCallbackData(cmd, args...).ToBase64()
+	return b
+}
+
+// SetCallbackDataCompact sets a structured callback payload encoded as compact text.
+func (b InlineKeyboardButtonBuilder) SetCallbackDataCompact(cmd string, args ...any) InlineKeyboardButtonBuilder {
+	b.url = ""
+	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.url = ""
+	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 {
+	b.url = ""
+	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,
-		CallbackData:      b.callbackData,
+		IconCustomEmojiID: b.emojiID,
+		CallbackData:      b.data,
 	}
 }
 
+// InlineKeyboard is a stateful builder for constructing Telegram inline keyboard layouts.
+//
+// Buttons are added row-by-row. When a row reaches maxRow, it is automatically flushed.
+// Call AddLine() to manually end a row, or Get() to finalize and retrieve the markup.
+//
+// The keyboard is not thread-safe. Build it in a single goroutine.
 type InlineKeyboard struct {
-	CurrentLine extypes.Slice[tgapi.InlineKeyboardButton]
-	Lines       [][]tgapi.InlineKeyboardButton
-	maxRow      int
+	CurrentLine extypes.Slice[tgapi.InlineKeyboardButton] // Current row being built
+	Lines       [][]tgapi.InlineKeyboardButton            // Completed rows
+	maxRow      int                                       // Max buttons per row (e.g., 3 or 4)
+
+	payloadType BotPayloadType // Serialization format for callback data (JSON or Base64)
 }
 
-func NewInlineKeyboard(maxRow int) *InlineKeyboard {
+// 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.
+func NewInlineKeyboardJSON(maxRow int) *InlineKeyboard {
+	return NewInlineKeyboard(BotPayloadJSON, maxRow)
+}
+
+// NewInlineKeyboardBase64 creates a new keyboard builder with the specified maximum
+// number of buttons per row, using Base64 encoding for button payloads.
+//
+// Example: NewInlineKeyboardBase64(3) creates a keyboard with at most 3 buttons per line.
+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.
+func NewInlineKeyboard(payloadType BotPayloadType, maxRow int) *InlineKeyboard {
 	return &InlineKeyboard{
 		CurrentLine: make(extypes.Slice[tgapi.InlineKeyboardButton], 0),
 		Lines:       make([][]tgapi.InlineKeyboardButton, 0),
 		maxRow:      maxRow,
+		payloadType: payloadType,
 	}
 }
 
+// SetPayloadType sets the keyboard-local serialization format for callback data added via
+// AddCallbackButton and AddCallbackButtonStyle methods.
+// It overrides the bot's default payload type for this keyboard only.
+func (in *InlineKeyboard) SetPayloadType(t BotPayloadType) *InlineKeyboard {
+	in.payloadType = t
+	return in
+}
+
+// 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()
@@ -74,27 +220,45 @@ func (in *InlineKeyboard) append(button tgapi.InlineKeyboardButton) *InlineKeybo
 	return in
 }
 
-func (in *InlineKeyboard) AddUrlButton(text, url string) *InlineKeyboard {
+// AddURLButton adds a button that opens a URL when pressed.
+// No callback data is attached.
+func (in *InlineKeyboard) AddURLButton(text, url string) *InlineKeyboard {
 	return in.append(tgapi.InlineKeyboardButton{Text: text, URL: url})
 }
-func (in *InlineKeyboard) AddUrlButtonStyle(text string, style tgapi.KeyboardButtonStyle, url string) *InlineKeyboard {
+
+// AddURLButtonStyle adds a button with a visual style that opens a URL.
+// Style must be one of: ButtonStyleDanger, ButtonStyleSuccess, ButtonStylePrimary.
+func (in *InlineKeyboard) AddURLButtonStyle(text string, style tgapi.KeyboardButtonStyle, url string) *InlineKeyboard {
 	return in.append(tgapi.InlineKeyboardButton{Text: text, Style: style, URL: url})
 }
-func (in *InlineKeyboard) AddCallbackButton(text string, cmd string, args ...any) *InlineKeyboard {
+
+// 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, cmd string, args ...any) *InlineKeyboard {
 	return in.append(tgapi.InlineKeyboardButton{
-		Text: text, CallbackData: NewCallbackData(cmd, args...).ToJson(),
+		Text:         text,
+		CallbackData: NewCallbackData(cmd, args...).Encode(in.payloadType),
 	})
 }
+
+// AddCallbackButtonStyle adds a styled callback button.
+// Style affects visual appearance; callback data is sent to bot on press.
 func (in *InlineKeyboard) AddCallbackButtonStyle(text string, style tgapi.KeyboardButtonStyle, cmd string, args ...any) *InlineKeyboard {
 	return in.append(tgapi.InlineKeyboardButton{
-		Text: text, Style: style,
-		CallbackData: NewCallbackData(cmd, args...).ToJson(),
+		Text:         text,
+		Style:        style,
+		CallbackData: NewCallbackData(cmd, args...).Encode(in.payloadType),
 	})
 }
-func (in *InlineKeyboard) AddButton(b InlineKbButtonBuilder) *InlineKeyboard {
+
+// 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 InlineKeyboardButtonBuilder) *InlineKeyboard {
 	return in.append(b.build())
 }
 
+// AddLine manually ends the current row and starts a new one.
+// If the current row is empty, nothing happens.
 func (in *InlineKeyboard) AddLine() *InlineKeyboard {
 	if in.CurrentLine.Len() == 0 {
 		return in
@@ -103,32 +267,113 @@ func (in *InlineKeyboard) AddLine() *InlineKeyboard {
 	in.CurrentLine = make(extypes.Slice[tgapi.InlineKeyboardButton], 0)
 	return in
 }
+
+// Get finalizes the keyboard and returns a tgapi.ReplyMarkup.
+// Automatically flushes the current line if not empty.
+//
+// Returns a pointer to a ReplyMarkup suitable for use with tgapi.SendMessage.
 func (in *InlineKeyboard) Get() *tgapi.ReplyMarkup {
 	if in.CurrentLine.Len() > 0 {
-		in.Lines = append(in.Lines, in.CurrentLine)
+		in.AddLine()
 	}
-	return &tgapi.ReplyMarkup{InlineKeyboard: in.Lines}
+	lines := make([][]tgapi.InlineKeyboardButton, len(in.Lines))
+	for i := range in.Lines {
+		lines[i] = append([]tgapi.InlineKeyboardButton(nil), in.Lines[i]...)
+	}
+	return &tgapi.ReplyMarkup{InlineKeyboard: lines}
 }
 
+// CallbackData represents the structured payload sent when an inline button
+// with callback data is pressed.
+//
+// This structure is serialized to JSON and sent to the bot as a string.
+// The bot should parse this back to determine the command and arguments.
+//
+// Example:
+//
+//	{"cmd":"delete_user","args":["123","confirm"]}
 type CallbackData struct {
-	Command string   `json:"cmd"`
-	Args    []string `json:"args"`
+	Command string   `json:"cmd"`  // The command name to route to
+	Args    []string `json:"args"` // Arguments passed as strings
 }
 
-func NewCallbackData(command string, args ...any) *CallbackData {
+// NewCallbackData creates a new CallbackData instance with the given command and args.
+//
+// All args are converted to strings using fmt.Sprint. This is safe for primitives
+// (int, string, bool, float64) but may not serialize complex structs meaningfully.
+//
+// Use this to build callback payloads for bot command routing.
+func NewCallbackData(command string, args ...any) CallbackData {
 	stringArgs := make([]string, len(args))
 	for i, arg := range args {
 		stringArgs[i] = fmt.Sprint(arg)
 	}
-	return &CallbackData{
-		Command: command,
-		Args:    stringArgs,
-	}
+	return CallbackData{Command: command, Args: stringArgs}
 }
-func (d *CallbackData) ToJson() string {
-	data, err := json.Marshal(d)
+
+// All To* encoders return an empty string when serialization fails. Telegram
+// rejects empty callback_data, so an empty result surfaces a real bug rather
+// than masking it with a stub payload that silently routes to no handler.
+// Build CallbackData from primitives (string, []string) only — the encoders
+// have no failure modes for that input.
+
+// ToJSON serializes the CallbackData to a JSON string.
+// Returns an empty string if serialization fails.
+func (d CallbackData) ToJSON() string {
+	data, err := encodeJSONPayload(d)
 	if err != nil {
-		return `{"cmd":""}`
+		return ""
 	}
-	return string(data)
+	return data
+}
+
+// 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 {
+	data, err := encodeBase64Payload(d)
+	if err != nil {
+		return ""
+	}
+	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, 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:
+		return d.ToJSON()
+	case BotPayloadCompact:
+		return d.ToCompact()
+	case BotPayloadCompactBase64:
+		return d.ToCompactBase64()
+	}
+	return ""
 }

keyboard_test.go

@@ -0,0 +1,254 @@
+package laniakea
+
+import (
+	"errors"
+	"reflect"
+	"strings"
+	"testing"
+)
+
+func TestInlineKeyboardWrapsRowsAndEncodesJSONPayloads(t *testing.T) {
+	kb := NewInlineKeyboardJSON(2).
+		AddCallbackButton("A", "cmd", 1).
+		AddCallbackButton("B", "cmd", 2).
+		AddCallbackButton("C", "cmd", 3)
+
+	markup := kb.Get()
+	if got := len(markup.InlineKeyboard); got != 2 {
+		t.Fatalf("unexpected row count: %d", got)
+	}
+	if got := len(markup.InlineKeyboard[0]); got != 2 {
+		t.Fatalf("unexpected first row size: %d", got)
+	}
+	if got := len(markup.InlineKeyboard[1]); got != 1 {
+		t.Fatalf("unexpected second row size: %d", got)
+	}
+	if !strings.Contains(markup.InlineKeyboard[0][0].CallbackData, `"cmd":"cmd"`) {
+		t.Fatalf("expected JSON callback payload, got %q", markup.InlineKeyboard[0][0].CallbackData)
+	}
+}
+
+func TestInlineKeyboardBuilderPreservesConfiguredButtonFields(t *testing.T) {
+	kb := NewInlineKeyboardBase64(3).
+		AddButton(
+			NewInlineKeyboardButton("Docs").
+				SetStyle(ButtonStylePrimary).
+				SetURL("https://example.test"),
+		)
+
+	button := kb.Get().InlineKeyboard[0][0]
+	if button.Style != ButtonStylePrimary {
+		t.Fatalf("unexpected style: %q", button.Style)
+	}
+	if button.URL != "https://example.test" {
+		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 TestInlineKeyboardButtonBuilderKeepsExactlyOneAction(t *testing.T) {
+	callback := NewInlineKeyboardButton("Action").
+		SetURL("https://example.test").
+		SetCallbackDataJSON("confirm").
+		build()
+	if callback.URL != "" || callback.CallbackData == "" {
+		t.Fatalf("callback action was not exclusive: %#v", callback)
+	}
+
+	link := NewInlineKeyboardButton("Action").
+		SetCallbackDataJSON("confirm").
+		SetURL("https://example.test").
+		build()
+	if link.URL == "" || link.CallbackData != "" {
+		t.Fatalf("URL action was not exclusive: %#v", link)
+	}
+}
+
+func TestInlineKeyboardGetReturnsIndependentMarkup(t *testing.T) {
+	keyboard := NewInlineKeyboardJSON(1).AddURLButton("Docs", "https://example.test")
+	first := keyboard.Get()
+	first.InlineKeyboard[0][0].Text = "mutated"
+
+	second := keyboard.Get()
+	if got := second.InlineKeyboard[0][0].Text; got != "Docs" {
+		t.Fatalf("Get exposed builder state for mutation: got %q", got)
+	}
+}
+
+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)
+	}
+}

l10n.go

@@ -1,26 +1,72 @@
 package laniakea
 
-// DictEntry {key:{ru:123,en:123}}
+import (
+	"maps"
+	"sync"
+)
+
+// DictEntry maps language codes to translated strings.
 type DictEntry map[string]string
+
+// L10n stores translations with a configurable fallback language and is safe for concurrent use.
 type L10n struct {
+	mu           sync.RWMutex
 	entries      map[string]DictEntry
 	fallbackLang string
 }
 
+// NewL10n creates a localization store with the given fallback language.
 func NewL10n(fallbackLanguage string) *L10n {
-	return &L10n{make(map[string]DictEntry), fallbackLanguage}
+	return &L10n{
+		entries:      make(map[string]DictEntry),
+		fallbackLang: fallbackLanguage,
+	}
 }
+
+// AddDictEntry stores translations for key.
 func (l *L10n) AddDictEntry(key string, value DictEntry) *L10n {
-	l.entries[key] = value
+	l.mu.Lock()
+	defer l.mu.Unlock()
+	if l.entries == nil {
+		l.entries = make(map[string]DictEntry)
+	}
+	l.entries[key] = cloneDictEntry(value)
 	return l
 }
+
+// GetFallbackLanguage returns the currently configured fallback language code.
 func (l *L10n) GetFallbackLanguage() string {
+	l.mu.RLock()
+	defer l.mu.RUnlock()
 	return l.fallbackLang
 }
+
+// Translate returns the translation for key in lang, falling back to the configured language or the key itself.
 func (l *L10n) Translate(lang, key string) string {
-	s, ok := l.entries[key]
-	if !ok {
+	l.mu.RLock()
+	defer l.mu.RUnlock()
+
+	entries, exists := l.entries[key]
+	if !exists {
 		return key
 	}
-	return s[lang]
+
+	if translation, ok := entries[lang]; ok {
+		return translation
+	}
+
+	if fallback, ok := entries[l.fallbackLang]; ok {
+		return fallback
+	}
+
+	return key
+}
+
+func cloneDictEntry(src DictEntry) DictEntry {
+	if src == nil {
+		return nil
+	}
+	cloned := make(DictEntry, len(src))
+	maps.Copy(cloned, src)
+	return cloned
 }

l10n_test.go

@@ -0,0 +1,77 @@
+package laniakea
+
+import (
+	"fmt"
+	"sync"
+	"testing"
+)
+
+func TestL10nTranslateUsesFallbackAndKey(t *testing.T) {
+	l10n := NewL10n("en").
+		AddDictEntry("greeting", DictEntry{"en": "Hello", "ru": "Privet"}).
+		AddDictEntry("partial", DictEntry{"ru": "Tolko ru"})
+
+	tests := []struct {
+		name string
+		lang string
+		key  string
+		want string
+	}{
+		{name: "exact match", lang: "ru", key: "greeting", want: "Privet"},
+		{name: "fallback language", lang: "es", key: "greeting", want: "Hello"},
+		{name: "missing fallback returns key", lang: "en", key: "partial", want: "partial"},
+		{name: "unknown key returns key", lang: "en", key: "unknown", want: "unknown"},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			if got := l10n.Translate(tt.lang, tt.key); got != tt.want {
+				t.Fatalf("unexpected translation: got %q want %q", got, tt.want)
+			}
+		})
+	}
+}
+
+func TestL10nAddDictEntryCopiesInput(t *testing.T) {
+	l10n := NewL10n("en")
+	entry := DictEntry{"en": "Hello"}
+
+	l10n.AddDictEntry("greeting", entry)
+	entry["en"] = "Mutated"
+
+	if got := l10n.Translate("en", "greeting"); got != "Hello" {
+		t.Fatalf("unexpected translation after external mutation: got %q", got)
+	}
+}
+
+func TestL10nZeroValueIsUsable(t *testing.T) {
+	var l10n L10n
+
+	l10n.AddDictEntry("greeting", DictEntry{"en": "Hello"})
+
+	if got := l10n.Translate("en", "greeting"); got != "Hello" {
+		t.Fatalf("unexpected translation from zero-value l10n: got %q", got)
+	}
+}
+
+func TestL10nConcurrentAccess(t *testing.T) {
+	l10n := NewL10n("en")
+	l10n.AddDictEntry("base", DictEntry{"en": "Hello"})
+
+	var wg sync.WaitGroup
+	for i := 0; i < 8; i++ {
+		wg.Add(1)
+		go func(i int) {
+			defer wg.Done()
+			for j := 0; j < 100; j++ {
+				l10n.AddDictEntry(fmt.Sprintf("key-%d-%d", i, j), DictEntry{"en": "value"})
+				_ = l10n.Translate("en", "base")
+			}
+		}(i)
+	}
+	wg.Wait()
+
+	if got := l10n.Translate("en", "base"); got != "Hello" {
+		t.Fatalf("unexpected translation after concurrent access: got %q", got)
+	}
+}

methods.go

@@ -1,51 +1,94 @@
 package laniakea
 
 import (
+	"context"
 	"encoding/json"
-	"fmt"
-	"io"
-	"net/http"
+	"iter"
 
-	"git.nix13.pw/scuroneko/laniakea/tgapi"
+	"git.scuroneko.dev/scuroneko/laniakea/tgapi"
 )
 
-func (bot *Bot[T]) Updates() ([]tgapi.Update, error) {
+// Updates fetches new updates from Telegram API using long polling.
+// It respects the bot's current update offset and automatically advances it
+// after successful retrieval. The method supports selective update types
+// through AllowedUpdates and includes optional request logging.
+//
+// Parameters:
+//   - ctx: request context used to cancel the in-flight long polling request
+//
+// Returns:
+//   - []tgapi.Update: slice of received updates (empty if none available)
+//   - error: any error encountered during the API call
+//
+// Behavior:
+//  1. Uses the bot's current update offset (via GetUpdateOffset)
+//  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 the configured PollTimeout
+// for new updates, unless ctx is canceled earlier. For non-blocking behavior,
+// consider using webhooks instead.
+//
+// Example:
+//
+//	updates, err := bot.Updates(ctx)
+//	if err != nil {
+//	    log.Fatal(err)
+//	}
+//	for _, update := range updates {
+//	    // process update
+//	}
+func (bot *Bot[T]) Updates(ctx context.Context) ([]tgapi.Update, error) {
 	offset := bot.GetUpdateOffset()
+	timeout := bot.pollTimeout
 	params := tgapi.UpdateParams{
-		Offset:         Ptr(offset),
-		Timeout:        Ptr(30),
+		Offset:         new(offset),
+		Timeout:        new(timeout),
 		AllowedUpdates: bot.GetUpdateTypes(),
 	}
 
-	updates, err := bot.api.GetUpdates(params)
+	zero := make([]tgapi.Update, 0)
+	updates, err := bot.api.GetUpdatesWithContext(ctx, params)
 	if err != nil {
-		return nil, err
+		return zero, err
 	}
 
-	for _, u := range updates {
-		bot.SetUpdateOffset(u.UpdateID + 1)
-		err = bot.GetQueue().Enqueue(&u)
-		if err != nil {
-			return nil, 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)
 		}
 	}
-	return updates, err
+	if len(updates) > 0 {
+		bot.SetUpdateOffset(updates[len(updates)-1].UpdateID + 1)
+	}
+	if updates == nil {
+		return zero, nil
+	}
+	return updates, nil
 }
 
-func (bot *Bot[T]) GetFileByLink(link string) ([]byte, error) {
-	u := fmt.Sprintf("https://api.telegram.org/file/bot%s/%s", bot.token, link)
-	res, err := http.Get(u)
-	if err != nil {
-		return nil, err
+// 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
+			}
+		}
 	}
-	defer res.Body.Close()
-	return io.ReadAll(res.Body)
 }

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

@@ -1,226 +1,866 @@
 package laniakea
 
 import (
+	"context"
+	"errors"
 	"fmt"
+	"log"
+	"reflect"
+	"strconv"
+	"strings"
 
-	"git.nix13.pw/scuroneko/laniakea/tgapi"
-	"git.nix13.pw/scuroneko/laniakea/utils"
-	"git.nix13.pw/scuroneko/slog"
+	"git.scuroneko.dev/scuroneko/laniakea/tgapi"
+	"git.scuroneko.dev/scuroneko/laniakea/tgrich"
+	"git.scuroneko.dev/scuroneko/sneklog/v2"
 )
 
-type MsgContext struct {
-	Api *tgapi.API
+// MessageContext holds the normalized per-update context passed to command, payload,
+// scene, middleware, and generic update handlers.
+//
+// MessageContext is populated from the current Telegram update before handler routing.
+// 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
-	Update          tgapi.Update
-	From            *tgapi.User
-	CallbackMsgId   int
-	CallbackQueryId string
-	FromID          int
-	Prefix          string
-	Text            string
-	Args            []string
+	// 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 *sneklog.Logger
+
+	// InlineMsgID is the inline message identifier for callback queries that target
+	// an inline message instead of a chat message.
+	InlineMsgID string
+	// CallbackMsgID is the message ID targeted by the current callback query when
+	// the callback comes from a chat message.
+	CallbackMsgID int
+	// 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
-	botLogger     *slog.Logger
 	l10n          *L10n
+	draftProvider *DraftProvider
+	payloadType   BotPayloadType
+	sceneRuntime  sceneRuntime
+	observer      Observer
+	botID         int64
+
+	ctx context.Context
 }
 
+// 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
+	ctx       *MessageContext // internal back-reference
 }
 
-func (ctx *MsgContext) edit(messageId int, text string, keyboard *InlineKeyboard) *AnswerMessage {
-	params := tgapi.EditMessageTextP{
-		MessageID: messageId,
-		ChatID:    ctx.Msg.Chat.ID,
+func (ctx *MessageContext) edit(messageID int, text string, keyboard *InlineKeyboard, parseMode tgapi.ParseMode) *AnswerMessage {
+	if err := validateMessageText(text); err != nil {
+		ctx.Logger.Errorln(err)
+		return nil
+	}
+	params := tgapi.EditMessageText{
 		Text:      text,
-		ParseMode: tgapi.ParseMD,
+		ParseMode: parseMode,
+	}
+	switch {
+	case messageID > 0 && ctx.Msg != nil:
+		params.MessageID = messageID
+		params.ChatID = ctx.Msg.Chat.ID
+	case ctx.InlineMsgID != "":
+		params.InlineMessageID = ctx.InlineMsgID
+	default:
+		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.botLogger.Errorln(err)
+		ctx.Logger.Errorln(err)
 		return nil
 	}
+	resultMessageID := messageID
+	if msg.MessageID > 0 {
+		resultMessageID = msg.MessageID
+	}
 	return &AnswerMessage{
-		MessageID: msg.MessageID, ctx: ctx, Text: text, IsMedia: false,
+		MessageID: resultMessageID, ctx: ctx, Text: text, IsMedia: false,
 	}
 }
+
+// Edit replaces the text of the message without changing the keyboard or parse mode.
+// Uses ParseNone (plain text).
 func (m *AnswerMessage) Edit(text string) *AnswerMessage {
-	return m.ctx.edit(m.MessageID, text, nil)
+	return m.ctx.edit(m.MessageID, text, nil, tgapi.ParseNone)
 }
-func (ctx *MsgContext) EditCallback(text string, keyboard *InlineKeyboard) *AnswerMessage {
-	if ctx.CallbackMsgId == 0 {
-		ctx.botLogger.Errorln("Can't edit non-callback update message")
+
+// EditMarkdown replaces the text of the message using MarkdownV2 formatting.
+//
+// ⚠️ 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.ParseMarkdownV2)
+}
+
+func (ctx *MessageContext) editCallback(text string, keyboard *InlineKeyboard, parseMode tgapi.ParseMode) *AnswerMessage {
+	if ctx.CallbackMsgID == 0 && ctx.InlineMsgID == "" {
+		ctx.Logger.Errorln(ErrCallbackMessageMissing)
 		return nil
 	}
-
-	return ctx.edit(ctx.CallbackMsgId, text, keyboard)
-}
-func (ctx *MsgContext) EditCallbackf(format string, keyboard *InlineKeyboard, args ...any) *AnswerMessage {
-	return ctx.EditCallback(fmt.Sprintf(format, args...), keyboard)
+	return ctx.edit(ctx.CallbackMsgID, text, keyboard, parseMode)
 }
 
-func (ctx *MsgContext) editPhotoText(messageId int, text string, kb *InlineKeyboard) *AnswerMessage {
-	params := tgapi.EditMessageCaptionP{
-		ChatID:    ctx.Msg.Chat.ID,
-		MessageID: messageId,
+// EditCallback edits the callback message using plain text (ParseNone).
+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 tgfmt.EscapeMarkdownV2() before passing here.
+func (ctx *MessageContext) EditCallbackMarkdown(text string, keyboard *InlineKeyboard) *AnswerMessage {
+	return ctx.editCallback(text, keyboard, tgapi.ParseMarkdownV2)
+}
+
+// EditCallbackf formats a string using fmt.Sprintf and edits the callback message with plain text.
+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 tgfmt.EscapeMarkdownV2() before passing here.
+func (ctx *MessageContext) EditCallbackfMarkdown(format string, keyboard *InlineKeyboard, args ...any) *AnswerMessage {
+	return ctx.editCallback(fmt.Sprintf(format, args...), keyboard, tgapi.ParseMarkdownV2)
+}
+
+func (ctx *MessageContext) editPhotoText(messageID int, text string, kb *InlineKeyboard, parseMode tgapi.ParseMode) *AnswerMessage {
+	if err := validateCaptionText(text); err != nil {
+		ctx.Logger.Errorln(err)
+		return nil
+	}
+	params := tgapi.EditMessageCaption{
 		Caption:   text,
-		ParseMode: tgapi.ParseMD,
+		ParseMode: parseMode,
+	}
+	switch {
+	case messageID > 0 && ctx.Msg != nil:
+		params.ChatID = ctx.Msg.Chat.ID
+		params.MessageID = messageID
+	case ctx.InlineMsgID != "":
+		params.InlineMessageID = ctx.InlineMsgID
+	default:
+		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.botLogger.Errorln(err)
+		ctx.Logger.Errorln(err)
+		return nil
+	}
+	resultMessageID := messageID
+	if msg.MessageID > 0 {
+		resultMessageID = msg.MessageID
 	}
 	return &AnswerMessage{
-		MessageID: msg.MessageID, ctx: ctx, Text: text, IsMedia: true,
+		MessageID: resultMessageID, ctx: ctx, Text: text, IsMedia: true,
 	}
 }
-func (m *AnswerMessage) EditCaption(text string) *AnswerMessage {
-	if m.MessageID == 0 {
-		m.ctx.botLogger.Errorln("Can't edit caption message, message id is zero")
-		return m
-	}
-	return m.ctx.editPhotoText(m.MessageID, text, nil)
-}
-func (m *AnswerMessage) EditCaptionKeyboard(text string, kb *InlineKeyboard) *AnswerMessage {
-	return m.ctx.editPhotoText(m.MessageID, text, kb)
-}
 
-func (ctx *MsgContext) answer(text string, keyboard *InlineKeyboard) *AnswerMessage {
-	params := tgapi.SendMessageP{
+// EditCaption edits the caption of a media message using plain text.
+func (m *AnswerMessage) EditCaption(text string) *AnswerMessage {
+	return m.ctx.editPhotoText(m.MessageID, text, nil, tgapi.ParseNone)
+}
+
+// EditCaptionMarkdown edits the caption of a media message using MarkdownV2.
+//
+// ⚠️ 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.ParseMarkdownV2)
+}
+
+// EditCaptionKeyboard edits the caption of a media message with a new inline keyboard (plain text).
+func (m *AnswerMessage) EditCaptionKeyboard(text string, kb *InlineKeyboard) *AnswerMessage {
+	return m.ctx.editPhotoText(m.MessageID, text, kb, tgapi.ParseNone)
+}
+
+// EditCaptionKeyboardMarkdown edits the caption of a media message with a new inline keyboard using MarkdownV2.
+//
+// ⚠️ WARNING: User input must be escaped with tgfmt.EscapeMarkdownV2() before passing here.
+func (m *AnswerMessage) EditCaptionKeyboardMarkdown(text string, kb *InlineKeyboard) *AnswerMessage {
+	return m.ctx.editPhotoText(m.MessageID, text, kb, tgapi.ParseMarkdownV2)
+}
+
+func (ctx *MessageContext) answer(text string, keyboard *InlineKeyboard, parseMode tgapi.ParseMode) *AnswerMessage {
+	if ctx.Msg == nil {
+		ctx.Logger.Errorln(ErrMessageContextNil)
+		return nil
+	}
+	if err := validateMessageText(text); err != nil {
+		ctx.Logger.Errorln(err)
+		return nil
+	}
+	params := tgapi.SendMessage{
 		ChatID:    ctx.Msg.Chat.ID,
 		Text:      text,
-		ParseMode: tgapi.ParseMD,
+		ParseMode: parseMode,
 	}
 	if keyboard != nil {
 		params.ReplyMarkup = keyboard.Get()
 	}
+	if ctx.Msg.MessageThreadID > 0 {
+		params.MessageThreadID = ctx.Msg.MessageThreadID
+	}
+	if ctx.Msg.DirectMessageTopic != nil {
+		params.DirectMessagesTopicID = ctx.Msg.DirectMessageTopic.TopicID
+	}
 
-	msg, err := ctx.Api.SendMessage(params)
+	msg, err := ctx.API.SendMessageWithContext(ctx.Context(), params)
 	if err != nil {
-		ctx.botLogger.Errorln(err)
+		ctx.Logger.Errorln(err)
 		return nil
 	}
 	return &AnswerMessage{
 		MessageID: msg.MessageID, ctx: ctx, IsMedia: false, Text: text,
 	}
 }
-func (ctx *MsgContext) Answer(text string) *AnswerMessage {
-	return ctx.answer(text, nil)
-}
-func (ctx *MsgContext) Answerf(template string, args ...any) *AnswerMessage {
-	return ctx.answer(fmt.Sprintf(template, args...), nil)
-}
-func (ctx *MsgContext) Keyboard(text string, kb *InlineKeyboard) *AnswerMessage {
-	return ctx.answer(text, kb)
+
+// Answer sends a plain text message (ParseNone).
+func (ctx *MessageContext) Answer(text string) *AnswerMessage {
+	return ctx.answer(text, nil, tgapi.ParseNone)
 }
 
-func (ctx *MsgContext) answerPhoto(photoId, text string, kb *InlineKeyboard) *AnswerMessage {
-	params := tgapi.SendPhotoP{
+// 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 tgfmt.EscapeMarkdownV2() before passing here.
+func (ctx *MessageContext) AnswerMarkdown(text string) *AnswerMessage {
+	return ctx.answer(text, nil, tgapi.ParseMarkdownV2)
+}
+
+// Answerf formats a string using fmt.Sprintf and sends it as a plain text message.
+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 tgfmt.EscapeMarkdownV2() before passing here.
+func (ctx *MessageContext) AnswerfMarkdown(template string, args ...any) *AnswerMessage {
+	return ctx.answer(fmt.Sprintf(template, args...), nil, tgapi.ParseMarkdownV2)
+}
+
+// Keyboard sends a message with an inline keyboard (plain text).
+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 tgfmt.EscapeMarkdownV2() before passing here.
+func (ctx *MessageContext) KeyboardMarkdown(text string, keyboard *InlineKeyboard) *AnswerMessage {
+	return ctx.answer(text, keyboard, tgapi.ParseMarkdownV2)
+}
+
+func (ctx *MessageContext) answerLong(text string, keyboard *InlineKeyboard, parseMode tgapi.ParseMode) []*AnswerMessage {
+	if parseMode != tgapi.ParseNone {
+		ctx.Logger.Errorln(ErrMessageSplitImpossible)
+		return nil
+	}
+	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: tgapi.ParseMD,
-		Photo:     photoId,
+		ParseMode: parseMode,
+		Photo:     photoID,
 	}
 	if kb != nil {
 		params.ReplyMarkup = kb.Get()
 	}
-	msg, err := ctx.Api.SendPhoto(params)
+	if ctx.Msg.MessageThreadID > 0 {
+		params.MessageThreadID = ctx.Msg.MessageThreadID
+	}
+	if ctx.Msg.DirectMessageTopic != nil {
+		params.DirectMessagesTopicID = int(ctx.Msg.DirectMessageTopic.TopicID)
+	}
+
+	msg, err := ctx.API.SendPhotoWithContext(ctx.Context(), params)
 	if err != nil {
-		ctx.botLogger.Errorln(err)
-		return &AnswerMessage{
-			ctx: ctx, Text: text, IsMedia: true,
-		}
+		ctx.Logger.Errorln(err)
+		return nil
 	}
 	return &AnswerMessage{
 		MessageID: msg.MessageID, ctx: ctx, Text: text, IsMedia: true,
 	}
 }
-func (ctx *MsgContext) AnswerPhoto(photoId, text string) *AnswerMessage {
-	return ctx.answerPhoto(photoId, text, nil)
-}
-func (ctx *MsgContext) AnswerPhotoKeyboard(photoId, text string, kb *InlineKeyboard) *AnswerMessage {
-	return ctx.answerPhoto(photoId, text, kb)
+
+// AnswerPhoto sends a photo with plain text caption.
+func (ctx *MessageContext) AnswerPhoto(photoID, text string) *AnswerMessage {
+	return ctx.answerPhoto(photoID, text, nil, tgapi.ParseNone)
 }
 
-func (ctx *MsgContext) delete(messageId int) {
-	_, err := ctx.Api.DeleteMessage(tgapi.DeleteMessageP{
-		ChatID:    ctx.Msg.Chat.ID,
-		MessageID: messageId,
-	})
-	if err != nil {
-		ctx.botLogger.Errorln(err)
-	}
-}
-func (m *AnswerMessage) Delete() {
-	m.ctx.delete(m.MessageID)
-}
-func (ctx *MsgContext) CallbackDelete() {
-	ctx.delete(ctx.CallbackMsgId)
+// AnswerPhotoMarkdown sends a photo with MarkdownV2 caption.
+//
+// ⚠️ WARNING: User input must be escaped with tgfmt.EscapeMarkdownV2() before passing here.
+func (ctx *MessageContext) AnswerPhotoMarkdown(photoID, text string) *AnswerMessage {
+	return ctx.answerPhoto(photoID, text, nil, tgapi.ParseMarkdownV2)
 }
 
-func (ctx *MsgContext) answerCallbackQuery(url, text string, showAlert bool) {
-	if len(ctx.CallbackQueryId) == 0 {
+// AnswerPhotoKeyboard sends a photo with caption and inline keyboard (plain text).
+func (ctx *MessageContext) AnswerPhotoKeyboard(photoID, text string, kb *InlineKeyboard) *AnswerMessage {
+	return ctx.answerPhoto(photoID, text, kb, tgapi.ParseNone)
+}
+
+// AnswerPhotoKeyboardMarkdown sends a photo with caption and inline keyboard using MarkdownV2.
+//
+// ⚠️ WARNING: User input must be escaped with tgfmt.EscapeMarkdownV2() before passing here.
+func (ctx *MessageContext) AnswerPhotoKeyboardMarkdown(photoID, text string, kb *InlineKeyboard) *AnswerMessage {
+	return ctx.answerPhoto(photoID, text, kb, tgapi.ParseMarkdownV2)
+}
+
+// AnswerPhotof formats a string and sends it as a photo caption (plain text).
+func (ctx *MessageContext) AnswerPhotof(photoID, template string, args ...any) *AnswerMessage {
+	return ctx.answerPhoto(photoID, fmt.Sprintf(template, args...), nil, tgapi.ParseNone)
+}
+
+// AnswerPhotofMarkdown formats a string and sends it as a photo caption using MarkdownV2.
+//
+// ⚠️ WARNING: User input must be escaped with tgfmt.EscapeMarkdownV2() before passing here.
+func (ctx *MessageContext) AnswerPhotofMarkdown(photoID, template string, args ...any) *AnswerMessage {
+	return ctx.answerPhoto(photoID, fmt.Sprintf(template, args...), nil, tgapi.ParseMarkdownV2)
+}
+
+func (ctx *MessageContext) delete(messageID int) {
+	if messageID == 0 {
+		ctx.Logger.Errorln(ErrMessageIDZero)
 		return
 	}
-	_, err := ctx.Api.AnswerCallbackQuery(tgapi.AnswerCallbackQueryP{
-		CallbackQueryID: ctx.CallbackQueryId,
+	if ctx.Msg == nil {
+		ctx.Logger.Errorln(ErrMessageContextNil)
+		return
+	}
+	_, err := ctx.API.DeleteMessageWithContext(ctx.Context(), tgapi.DeleteMessage{
+		ChatID:    ctx.Msg.Chat.ID,
+		MessageID: messageID,
+	})
+	if err != nil {
+		ctx.Logger.Errorln(err)
+	}
+}
+
+// Delete removes the message associated with this AnswerMessage.
+func (m *AnswerMessage) Delete() { m.ctx.delete(m.MessageID) }
+
+// CallbackDelete deletes the message that triggered the callback query.
+func (ctx *MessageContext) CallbackDelete() {
+	if ctx.CallbackMsgID == 0 {
+		ctx.Logger.Errorln(ErrCallbackMessageMissing)
+		return
+	}
+	ctx.delete(ctx.CallbackMsgID)
+}
+
+func (ctx *MessageContext) answerCallbackQuery(url, text string, showAlert bool) {
+	if len(ctx.CallbackQueryID) == 0 {
+		return
+	}
+	_, err := ctx.API.AnswerCallbackQueryWithContext(ctx.Context(), tgapi.AnswerCallbackQuery{
+		CallbackQueryID: ctx.CallbackQueryID,
 		Text:            text, ShowAlert: showAlert, URL: url,
 	})
 	if err != nil {
-		ctx.botLogger.Errorln(err)
+		ctx.Logger.Errorln(err)
 	}
 }
-func (ctx *MsgContext) AnswerCbQuery() {
-	ctx.answerCallbackQuery("", "", false)
-}
-func (ctx *MsgContext) AnswerCbQueryText(text string) {
-	ctx.answerCallbackQuery("", text, false)
-}
-func (ctx *MsgContext) AnswerCbQueryAlert(text string) {
-	ctx.answerCallbackQuery("", text, true)
-}
-func (ctx *MsgContext) AnswerCbQueryUrl(u string) {
-	ctx.answerCallbackQuery(u, "", false)
-}
 
-func (ctx *MsgContext) SendAction(action tgapi.ChatActionType) {
-	_, err := ctx.Api.SendChatAction(tgapi.SendChatActionP{
+// AnswerCallback answers the callback query with no text or alert.
+func (ctx *MessageContext) AnswerCallback() { ctx.answerCallbackQuery("", "", false) }
+
+// AnswerCallbackText answers the callback query with a text notification.
+func (ctx *MessageContext) AnswerCallbackText(text string) { ctx.answerCallbackQuery("", text, false) }
+
+// AnswerCallbackAlert answers the callback query with a user-visible alert.
+func (ctx *MessageContext) AnswerCallbackAlert(text string) { ctx.answerCallbackQuery("", text, true) }
+
+// AnswerCallbackURL answers the callback query with a URL redirect.
+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 *MessageContext) SendAction(action tgapi.ChatActionType) {
+	if ctx.Msg == nil {
+		ctx.Logger.Errorln(ErrMessageContextNil)
+		return
+	}
+	params := tgapi.SendChatAction{
 		ChatID: ctx.Msg.Chat.ID, Action: action,
-	})
+	}
+	if ctx.Msg.MessageThreadID > 0 {
+		params.MessageThreadID = ctx.Msg.MessageThreadID
+	}
+	_, err := ctx.API.SendChatActionWithContext(ctx.Context(), params)
 	if err != nil {
-		ctx.botLogger.Errorln(err)
+		ctx.Logger.Errorln(err)
 	}
 }
 
-func (ctx *MsgContext) error(err error) {
-	text := fmt.Sprintf(ctx.errorTemplate, utils.EscapeMarkdown(err.Error()))
+func (ctx *MessageContext) 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)
+		ctx.answer(text, nil, tgapi.ParseNone)
 	}
-	ctx.botLogger.Errorln(err)
-}
-func (ctx *MsgContext) Error(err error) {
-	ctx.error(err)
 }
 
-func (ctx *MsgContext) Translate(key string) string {
+// Error routes err through the centralized handler error path.
+//
+// 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 *MessageContext) newDraft(parseMode tgapi.ParseMode) *Draft {
+	if ctx.Msg == nil {
+		ctx.Logger.Errorln(ErrMessageContextNil)
+		return nil
+	}
+	if ctx.API == nil {
+		ctx.Logger.Errorln(ErrAPIIsNil)
+		return nil
+	}
+	if ctx.draftProvider == nil {
+		ctx.Logger.Errorln(ErrDraftProviderNil)
+		return nil
+	}
+
+	draft := ctx.draftProvider.NewDraft(parseMode).SetChat(ctx.Msg.Chat.ID, ctx.Msg.MessageThreadID)
+	return draft
+}
+
+// NewDraft creates a new message draft associated with the current chat.
+// Draft sends are rate-limited by the API client.
+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.
+// Draft sends are rate-limited by the API client.
+func (ctx *MessageContext) NewDraftMarkdown() *Draft {
+	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 *MessageContext) Translate(key string) string {
 	if ctx.From == nil {
 		return key
 	}
 	lang := Val(ctx.From.LanguageCode, ctx.l10n.GetFallbackLanguage())
 	return ctx.l10n.Translate(lang, key)
 }
+
+// NewInlineKeyboard creates a new keyboard builder with the context's payload
+// encoding type and the specified maximum number of buttons per row.
+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)
+}
+
+func (ctx *MessageContext) richAnswer(rich tgapi.InputRichMessage, keyboard *InlineKeyboard) *AnswerMessage {
+	if ctx.Msg == nil {
+		ctx.Logger.Errorln(ErrMessageContextNil)
+		return nil
+	}
+	params := tgapi.SendRichMessage{
+		ChatID:      ctx.Msg.Chat.ID,
+		RichMessage: rich,
+	}
+	if keyboard != nil {
+		params.ReplyMarkup = keyboard.Get()
+	}
+	if ctx.Msg.MessageThreadID > 0 {
+		params.MessageThreadID = int64(ctx.Msg.MessageThreadID)
+	}
+	if ctx.Msg.DirectMessageTopic != nil {
+		params.DirectMessagesTopicID = ctx.Msg.DirectMessageTopic.TopicID
+	}
+
+	msg, err := ctx.API.SendRichMessageWithContext(ctx.Context(), params)
+	if err != nil {
+		ctx.Logger.Errorln(err)
+		return nil
+	}
+	return &AnswerMessage{
+		MessageID: msg.MessageID, ctx: ctx, Text: rich.HTML, IsMedia: false,
+	}
+}
+
+func (ctx *MessageContext) richBlocksAnswer(keyboard *InlineKeyboard, blocks ...tgapi.InputRichBlock) *AnswerMessage {
+	rich, err := tgrich.BuildHTML(blocks...)
+	if err != nil {
+		ctx.Logger.Errorln(err)
+		return nil
+	}
+	return ctx.richAnswer(rich, keyboard)
+}
+
+// RichAnswer builds and sends input rich-message blocks.
+//
+// Since: Bot API 10.2
+func (ctx *MessageContext) RichAnswer(blocks ...tgapi.InputRichBlock) *AnswerMessage {
+	return ctx.richBlocksAnswer(nil, blocks...)
+}
+
+// RichAnswerKeyboard builds and sends input rich-message blocks with an inline keyboard.
+//
+// Since: Bot API 10.2
+func (ctx *MessageContext) RichAnswerKeyboard(keyboard *InlineKeyboard, blocks ...tgapi.InputRichBlock) *AnswerMessage {
+	return ctx.richBlocksAnswer(keyboard, blocks...)
+}

msg_context_test.go

@@ -0,0 +1,656 @@
+package laniakea
+
+import (
+	"encoding/json"
+	"errors"
+	"io"
+	"net/http"
+	"reflect"
+	"strings"
+	"testing"
+
+	"git.scuroneko.dev/scuroneko/laniakea/tgapi"
+	"git.scuroneko.dev/scuroneko/laniakea/tgrich"
+	"git.scuroneko.dev/scuroneko/sneklog/v2"
+)
+
+func TestRichAnswerBuildsInputBlocks(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.Fatal(err)
+		}
+		if err := json.Unmarshal(body, &gotBody); err != nil {
+			t.Fatal(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() { _ = api.Close() }()
+	ctx := &MessageContext{
+		API:    api,
+		Msg:    &tgapi.Message{Chat: &tgapi.Chat{ID: 42, Type: tgapi.ChatTypePrivate}},
+		Logger: sneklog.NewLogger(),
+	}
+
+	answer := ctx.RichAnswer(tgrich.P(tgrich.Bold(tgrich.Text("ready"))))
+	if answer == nil {
+		t.Fatal("RichAnswer() returned nil")
+	}
+	rich, ok := gotBody["rich_message"].(map[string]any)
+	if !ok || rich["html"] != "<p><b>ready</b></p>" {
+		t.Fatalf("rich_message = %#v", gotBody["rich_message"])
+	}
+	if _, exists := rich["skip_entity_detection"]; exists {
+		t.Fatalf("rich_message unexpectedly disables entity detection: %#v", rich)
+	}
+}
+
+func TestRichAnswerRejectsInvalidBlocksWithoutRequest(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() { _ = api.Close() }()
+	ctx := &MessageContext{
+		API:    api,
+		Msg:    &tgapi.Message{Chat: &tgapi.Chat{ID: 42, Type: tgapi.ChatTypePrivate}},
+		Logger: sneklog.NewLogger(),
+	}
+
+	if answer := ctx.RichAnswer(tgrich.H(tgrich.Text("invalid"), 0)); answer != nil {
+		t.Fatal("RichAnswer() returned an answer for an invalid heading")
+	}
+}
+
+func TestAnswerPhotoIncludesDirectMessagesTopicID(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":{"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},
+			DirectMessageTopic: &tgapi.DirectMessageTopic{TopicID: 77},
+		},
+		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)
+	}
+	if got := gotBody["direct_messages_topic_id"]; got != float64(77) {
+		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,214 @@
+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"
+	// HandlerMiddlewareKind identifies middleware execution.
+	HandlerMiddlewareKind HandlerEventKind = "middleware"
+	// 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()
+}
+
+func emitContextError(ctx *MessageContext, event ErrorEvent) {
+	if ctx == nil {
+		return
+	}
+	if ctx.Logger != nil {
+		ctx.Logger.Errorln(event.Err)
+	}
+	if ctx.observer == nil {
+		return
+	}
+	defer func() {
+		if recovered := recover(); recovered != nil && ctx.Logger != nil {
+			ctx.Logger.Errorln(fmt.Sprintf("panic in observer: %v", recovered))
+		}
+	}()
+	ctx.observer.OnError(ctx.Context(), event)
+}
+
+// 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 {
+			if bot.logger != nil {
+				bot.logger.Errorln(fmt.Sprintf("panic in observer: %v", r))
+			}
+		}
+	}()
+	bot.emitEvent(ctx, event)
+}
+
+func (bot *Bot[T]) emitEvent(ctx context.Context, event Event) {
+	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,144 +2,285 @@ package laniakea
 
 import (
 	"errors"
-	"regexp"
+	"fmt"
 
-	"git.nix13.pw/scuroneko/extypes"
+	"git.scuroneko.dev/scuroneko/extypes"
+	"git.scuroneko.dev/scuroneko/laniakea/tgapi"
+	"git.scuroneko.dev/scuroneko/laniakea/utils"
+	"git.scuroneko.dev/scuroneko/sneklog/v2"
 )
 
-const (
-	CommandValueStringType CommandValueType = "string"
-	CommandValueIntType    CommandValueType = "int"
-	CommandValueBoolType   CommandValueType = "bool"
-	CommandValueAnyType    CommandValueType = "any"
-)
+// 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 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      *sneklog.Logger
+	loggerOwned bool // true when the logger was created by the bot during registration; only owned loggers are closed by Close
 
-var (
-	CommandRegexInt    = regexp.MustCompile("\\d+")
-	CommandRegexString = regexp.MustCompile(".+")
-)
+	messageFallback CommandExecutor[T]
+	handlers        map[tgapi.UpdateType]CommandExecutor[T]
 
-var (
-	ErrCmdArgCountMismatch  = errors.New("command arg count mismatch")
-	ErrCmdArgRegexpMismatch = errors.New("command arg regexp mismatch")
-)
-
-type CommandValueType string
-type CommandArg struct {
-	valueType CommandValueType
-	text      string
-	regex     *regexp.Regexp
-	required  bool
+	onClose func() error
 }
 
-func NewCommandArg(text string, valueType CommandValueType) *CommandArg {
-	regex := CommandRegexString
-	switch valueType {
-	case CommandValueIntType:
-		regex = CommandRegexInt
-	}
-	return &CommandArg{valueType, text, regex, false}
-}
-func (c *CommandArg) SetRequired() *CommandArg {
-	c.required = true
-	return c
-}
-
-type CommandExecutor[T DbContext] func(ctx *MsgContext, dbContext *T)
-
-type Command[T DbContext] struct {
-	command     string
-	description string
-	exec        CommandExecutor[T]
-	args        extypes.Slice[CommandArg]
-	middlewares extypes.Slice[Middleware[T]]
-	skipAutoCmd bool
-}
-
-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}
-}
-func (c *Command[T]) Use(m Middleware[T]) *Command[T] {
-	c.middlewares = c.middlewares.Push(m)
-	return c
-}
-func (c *Command[T]) SetDescription(desc string) *Command[T] {
-	c.description = desc
-	return c
-}
-func (c *Command[T]) SkipCommandAutoGen() *Command[T] {
-	c.skipAutoCmd = true
-	return c
-}
-func (c *Command[T]) validateArgs(args []string) error {
-	cmdArgs := c.args.Filter(func(e CommandArg) bool { return !e.required })
-	if len(args) < cmdArgs.Len() {
-		return ErrCmdArgCountMismatch
-	}
-
-	for i, arg := range args {
-		if i >= c.args.Len() {
-			break
-		}
-		cmdArg := c.args.Get(i)
-		if cmdArg.regex == nil {
-			continue
-		}
-		if !cmdArg.regex.MatchString(arg) {
-			return ErrCmdArgRegexpMismatch
-		}
-	}
-	return nil
-}
-
-type Plugin[T DbContext] struct {
-	Name        string
-	Commands    map[string]Command[T]
-	Payloads    map[string]Command[T]
-	Middlewares extypes.Slice[Middleware[T]]
-}
-
-func NewPlugin[T DbContext](name string) *Plugin[T] {
+// NewPlugin creates a new Plugin with the given name.
+func NewPlugin[T AppData](name string) *Plugin[T] {
 	return &Plugin[T]{
-		name, map[string]Command[T]{},
-		map[string]Command[T]{}, extypes.Slice[Middleware[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]),
 	}
 }
 
+// AddCommand registers a command in the plugin.
 func (p *Plugin[T]) AddCommand(command *Command[T]) *Plugin[T] {
-	p.Commands[command.command] = *command
-	return p
-}
-func (p *Plugin[T]) NewCommand(exec CommandExecutor[T], command string, args ...CommandArg) *Command[T] {
-	return NewCommand(exec, command, args...)
-}
-func (p *Plugin[T]) AddPayload(command *Command[T]) *Plugin[T] {
-	p.Payloads[command.command] = *command
-	return p
-}
-func (p *Plugin[T]) AddMiddleware(middleware Middleware[T]) *Plugin[T] {
-	p.Middlewares = p.Middlewares.Push(middleware)
+	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
 }
 
-func (p *Plugin[T]) executeCmd(cmd string, ctx *MsgContext, dbContext *T) {
-	command := p.Commands[cmd]
+// Command creates and immediately adds a new command to the plugin.
+// Returns the created command for further configuration.
+func (p *Plugin[T]) Command(command string, exec CommandExecutor[T], args ...CommandArg) *Command[T] {
+	cmd := NewCommand(command, exec, args...)
+	p.AddCommand(cmd)
+	return cmd
+}
+
+// AddPayload registers a payload (e.g., callback query data) in the plugin.
+// Payloads are triggered by inline button callback_data, not by message text.
+func (p *Plugin[T]) AddPayload(command *Command[T]) *Plugin[T] {
+	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
+}
+
+// Payload creates and immediately adds a new payload command to the plugin.
+// Returns the created payload command for further configuration.
+func (p *Plugin[T]) Payload(command string, exec CommandExecutor[T], args ...CommandArg) *Command[T] {
+	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(), utils.LogFormatText, nil)
+			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 registered through AddUpdateHandler. Use AddPayload/Payload or AddCommand/Command", t)
+		return p
+	}
+	p.handlers[t] = handler
+	return p
+}
+
+// AddMiddleware adds a middleware to the plugin's global middleware chain.
+// Middlewares are executed before any command or payload.
+func (p *Plugin[T]) AddMiddleware(middleware Middleware[T]) *Plugin[T] {
+	p.middlewares = p.middlewares.Push(middleware)
+	return p
+}
+
+// SkipCommandAutoGen marks the entire plugin to be excluded from auto-generated help menus.
+func (p *Plugin[T]) SkipCommandAutoGen() *Plugin[T] {
+	p.skipAutoCmd = true
+	return p
+}
+
+// SetLogger sets the logger used for this plugin's handlers.
+//
+// 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 *sneklog.Logger) *Plugin[T] {
+	p.logger = l
+	return p
+}
+
+// RemoveLogger clears the custom logger for this plugin.
+//
+// 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]) RemoveLogger() *Plugin[T] {
+	p.logger = nil
+	return p
+}
+
+// SetOnClose registers a callback invoked from Plugin.Close after the plugin
+// logger is closed.
+//
+// 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]) SetOnClose(f func() error) *Plugin[T] {
+	p.onClose = f
+	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 && p.loggerOwned {
+		if err := p.logger.Close(); err != nil {
+			e = append(e, err)
+		}
+	}
+	if p.onClose != nil {
+		if err := p.onClose(); err != nil {
+			e = append(e, err)
+		}
+	}
+	return errors.Join(e...)
+}
+
+func (p *Plugin[T]) executeCmd(cmd string, ctx *MessageContext, db T) error {
+	command, exists := p.commands[cmd]
+	if !exists {
+		return AsInternalError(errCommandNotFound)
+	}
+
 	if err := command.validateArgs(ctx.Args); err != nil {
-		ctx.error(err)
-		return
+		return AsUserError(err)
 	}
-	command.exec(ctx, dbContext)
-}
-func (p *Plugin[T]) executePayload(payload string, ctx *MsgContext, dbContext *T) {
-	pl := p.Payloads[payload]
-	if err := pl.validateArgs(ctx.Args); err != nil {
-		ctx.error(err)
-		return
+
+	// Run command-specific middlewares
+	for _, m := range command.middlewares {
+		if !m.Execute(ctx, db) {
+			return AsInternalError(errors.New("middleware blocked call"))
+		}
 	}
-	pl.exec(ctx, dbContext)
+
+	// Execute command
+	return command.exec(ctx, db)
 }
-func (p *Plugin[T]) executeMiddlewares(ctx *MsgContext, db *T) bool {
-	for _, m := range p.Middlewares {
+
+func (p *Plugin[T]) executePayload(payload string, ctx *MessageContext, db T) error {
+	command, exists := p.payloads[payload]
+	if !exists {
+		return AsInternalError(errPayloadNotFound)
+	}
+
+	if err := command.validateArgs(ctx.Args); err != nil {
+		return AsUserError(err)
+	}
+
+	// Run command-specific middlewares
+	for _, m := range command.middlewares {
+		if !m.Execute(ctx, db) {
+			return AsInternalError(errors.New("middleware blocked call"))
+		}
+	}
+
+	// Execute payload
+	return command.exec(ctx, db)
+}
+
+func (p *Plugin[T]) executeMiddlewares(ctx *MessageContext, db T) bool {
+	for _, m := range p.middlewares {
 		if !m.Execute(ctx, db) {
 			return false
 		}
@@ -147,32 +288,84 @@ func (p *Plugin[T]) executeMiddlewares(ctx *MsgContext, db *T) bool {
 	return true
 }
 
-type MiddlewareExecutor[T DbContext] func(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 AppData] func(ctx *MessageContext, db T) bool
 
-// Middleware
-// When async, returned value ignored
-type Middleware[T DbContext] struct {
-	name     string
-	executor MiddlewareExecutor[T]
-	order    int
-	async    bool
+// ErrMiddlewareExecutorNil reports an attempt to execute middleware without a callback.
+var ErrMiddlewareExecutorNil = errors.New("middleware executor is nil")
+
+// Middleware represents a reusable execution interceptor.
+// Can be synchronous (blocking) or asynchronous (non-blocking).
+type Middleware[T AppData] struct {
+	name     string                // Human-readable name for logging/debugging
+	executor MiddlewareExecutor[T] // Function to execute
+	order    int                   // Sort order for bot-level middleware ordering
+	async    bool                  // If true, runs in goroutine and doesn't block
 }
 
-func NewMiddleware[T DbContext](name string, executor MiddlewareExecutor[T]) *Middleware[T] {
-	return &Middleware[T]{name, executor, 0, false}
+// NewMiddleware creates a new synchronous middleware.
+func NewMiddleware[T AppData](name string, executor MiddlewareExecutor[T]) Middleware[T] {
+	return Middleware[T]{name, executor, 0, false}
 }
-func (m *Middleware[T]) SetOrder(order int) *Middleware[T] {
+
+// SetOrder sets the bot-level middleware execution order.
+func (m Middleware[T]) SetOrder(order int) Middleware[T] {
 	m.order = order
 	return m
 }
-func (m *Middleware[T]) SetAsync(async bool) *Middleware[T] {
+
+// SetAsync marks the middleware to run asynchronously.
+// Execution continues regardless of its return value.
+func (m Middleware[T]) SetAsync(async bool) Middleware[T] {
 	m.async = async
 	return m
 }
-func (m *Middleware[T]) Execute(ctx *MsgContext, db *T) bool {
+
+// Execute runs the middleware.
+// If async, runs in a goroutine and returns true immediately.
+// Otherwise, returns the result of the executor.
+//
+// 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.executor == nil {
+		reportMiddlewareError(ctx, m.name, ErrMiddlewareExecutorNil)
+		return false
+	}
 	if m.async {
-		go m.executor(ctx, db)
+		ctxCopy := *ctx
+		go func(ctx MessageContext) {
+			defer func() {
+				if recovered := recover(); recovered != nil {
+					reportMiddlewareError(&ctx, m.name, fmt.Errorf("middleware %q panicked: %v", m.name, recovered))
+				}
+			}()
+			m.executor(&ctx, db)
+		}(ctxCopy)
 		return true
 	}
 	return m.executor(ctx, db)
 }
+
+func reportMiddlewareError(ctx *MessageContext, name string, err error) {
+	event := ErrorEvent{
+		Plugin:      "bot",
+		HandlerKind: HandlerMiddlewareKind,
+		HandlerName: name,
+		Err:         err,
+		UserFacing:  false,
+	}
+	if ctx != nil {
+		event.UpdateID = ctx.Update.UpdateID
+		event.UpdateType = ctx.Update.Type
+		event.FromID = ctx.FromID
+		event.ChatID = ctx.ChatID
+	}
+	emitContextError(ctx, event)
+}

plugins_test.go

@@ -0,0 +1,173 @@
+package laniakea
+
+import (
+	"context"
+	"errors"
+	"testing"
+	"time"
+
+	"git.scuroneko.dev/scuroneko/laniakea/tgapi"
+)
+
+type middlewareErrorObserver struct {
+	testObserver
+	errors chan ErrorEvent
+}
+
+func (o *middlewareErrorObserver) OnError(_ context.Context, event ErrorEvent) {
+	o.errors <- event
+}
+
+func TestAsyncMiddlewareRecoversPanic(t *testing.T) {
+	observer := &middlewareErrorObserver{errors: make(chan ErrorEvent, 1)}
+	ctx := &MessageContext{
+		Update:   tgapi.Update{UpdateID: 7, Type: tgapi.UpdateTypeMessage},
+		FromID:   42,
+		ChatID:   100,
+		observer: observer,
+	}
+	middleware := NewMiddleware[NoData]("panic", func(ctx *MessageContext, db NoData) bool {
+		panic("boom")
+	}).SetAsync(true)
+
+	if !middleware.Execute(ctx, NoData{}) {
+		t.Fatal("async middleware blocked execution")
+	}
+	select {
+	case event := <-observer.errors:
+		if event.HandlerKind != HandlerMiddlewareKind || event.HandlerName != "panic" {
+			t.Fatalf("unexpected error event: %#v", event)
+		}
+		if event.Err == nil {
+			t.Fatal("panic error was not reported")
+		}
+	case <-time.After(time.Second):
+		t.Fatal("timed out waiting for async middleware error")
+	}
+}
+
+func TestMiddlewareRejectsNilExecutor(t *testing.T) {
+	observer := &middlewareErrorObserver{errors: make(chan ErrorEvent, 1)}
+	ctx := &MessageContext{observer: observer}
+	middleware := NewMiddleware[NoData]("nil", nil)
+
+	if middleware.Execute(ctx, NoData{}) {
+		t.Fatal("nil middleware executor was accepted")
+	}
+	event := <-observer.errors
+	if !errors.Is(event.Err, ErrMiddlewareExecutorNil) {
+		t.Fatalf("error = %v, want ErrMiddlewareExecutorNil", event.Err)
+	}
+}
+
+func TestValidateArgsRequiresFullMatch(t *testing.T) {
+	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)
+	}
+	if err := intCmd.validateArgs([]string{"123abc"}); !errors.Is(err, ErrCmdArgRegexpMismatch) {
+		t.Fatalf("expected ErrCmdArgRegexpMismatch for partial int match, got %v", err)
+	}
+
+	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)
+	}
+	if err := boolCmd.validateArgs([]string{"falsey"}); !errors.Is(err, ErrCmdArgRegexpMismatch) {
+		t.Fatalf("expected ErrCmdArgRegexpMismatch for partial bool match, got %v", err)
+	}
+}
+
+func TestValidateArgsEnforcesRequiredArgIndex(t *testing.T) {
+	cmd := NewCommand(
+		"mixed",
+		func(ctx *MessageContext, db NoData) error { return nil },
+		NewCommandArg("optional"),
+		NewCommandArg("required").SetRequired(),
+	)
+
+	if err := cmd.validateArgs([]string{"only-optional"}); !errors.Is(err, ErrCmdArgCountMismatch) {
+		t.Fatalf("expected ErrCmdArgCountMismatch when required second arg is missing, got %v", err)
+	}
+	if err := cmd.validateArgs([]string{"optional", "required"}); err != nil {
+		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

@@ -1,74 +1,181 @@
 package laniakea
 
 import (
+	"context"
+	"fmt"
 	"time"
 )
 
-type RunnerFn[T DbContext] func(*Bot[T]) error
-type Runner[T DbContext] struct {
-	name    string
-	onetime bool
-	async   bool
-	timeout time.Duration
-	fn      RunnerFn[T]
+// 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 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 Async and Every. Once the
+// bot's runtime has started executing the runner, it should not be modified.
+//
+// Execution semantics:
+//   - every=0, async=true:  Run once in a goroutine (non-blocking, default).
+//   - every=0, async=false: Run once synchronously (blocks runtime startup).
+//   - every>0, async=true:  Run repeatedly in a goroutine with the given interval.
+//   - every>0, async=false: Invalid configuration — skipped with a warning.
+type Runner[T AppData] struct {
+	name  string        // Human-readable name for logging
+	async bool          // If true, runs in a goroutine; else, runs synchronously
+	every time.Duration // Interval between periodic executions; zero means one-shot
+	fn    RunnerFn[T]   // The function to execute
 }
 
-func NewRunner[T DbContext](name string, fn RunnerFn[T]) *Runner[T] {
-	return &Runner[T]{
-		name: name, fn: fn, async: true,
+func executeRunner[T AppData](runner Runner[T], bot *Bot[T]) (err error) {
+	defer func() {
+		if recovered := recover(); recovered != nil {
+			err = fmt.Errorf("runner %q panicked: %v", runner.name, recovered)
+		}
+	}()
+	if runner.fn == nil {
+		return fmt.Errorf("runner %q has no function", runner.name)
 	}
-}
-func (b *Runner[T]) Onetime(onetime bool) *Runner[T] {
-	b.onetime = onetime
-	return b
-}
-func (b *Runner[T]) Async(async bool) *Runner[T] {
-	b.async = async
-	return b
-}
-func (b *Runner[T]) Timeout(timeout time.Duration) *Runner[T] {
-	b.timeout = timeout
-	return b
+	return runner.fn(bot)
 }
 
-func (bot *Bot[T]) ExecRunners() {
+// NewRunner creates a new Runner with the given name and function.
+//
+// The default configuration is async=true and every=0, i.e. a one-shot
+// goroutine that fires once when the bot runtime starts. Use Async and Every
+// 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, fn: fn, async: true, every: 0}
+}
+
+// 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: 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
+}
+
+// Every sets the interval between repeated executions of a periodic runner.
+//
+// A zero value (the default) keeps the runner one-shot. A positive value
+// schedules the runner to fire repeatedly with the given interval and
+// requires async=true; periodic sync runners are skipped with a warning.
+func (r Runner[T]) Every(timeout time.Duration) Runner[T] {
+	r.every = timeout
+	return r
+}
+
+// ExecRunners executes all runners registered on the Bot with context-based lifecycle management.
+//
+// Execution semantics by configuration:
+//   - every=0, async=true:  Runs once in a goroutine (fire and forget).
+//   - 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().
+//   - every>0, async=false: Skipped with a warning (invalid configuration).
+//
+// Background runners listen for ctx.Done() and gracefully shut down when the context is canceled.
+//
+// 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 {
-		if !runner.onetime && !runner.async {
-			bot.logger.Warnf("Runner %s not onetime, but sync\n", runner.name)
+		if runner.every > 0 && !runner.async {
+			bot.logger.Warnf("Runner %q is periodic but sync; skipping (use Async(true))\n", runner.name)
 			continue
 		}
-		if !runner.onetime && runner.async && runner.timeout == (time.Second*0) {
-			bot.logger.Warnf("Background runner \"%s\" should have timeout", runner.name)
-		}
 
-		if runner.async && runner.onetime {
-			go func() {
-				err := runner.fn(bot)
+		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 := executeRunner(r, bot)
+				bot.safeEmitEvent(ctx, RunnerFinishedEvent{
+					Name:     r.name,
+					Duration: time.Since(startedAt),
+					Err:      err,
+				})
 				if err != nil {
-					bot.logger.Warnf("Runner %s failed: %s\n", runner.name, err)
+					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)
 				}
-			}()
-		} else if !runner.async && runner.onetime {
+			}(runner)
+		} else if runner.every == 0 && !runner.async {
+			// One-time sync: block until done
 			t := time.Now()
-			err := runner.fn(bot)
+			err := executeRunner(runner, 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 %s>=2s", runner.name, elapsed)
+				bot.logger.Warnf("Runner %s too slow. Elapsed time %v >= 2s\n", runner.name, elapsed)
 			}
-		} else if !runner.onetime {
-			go func() {
+		} 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.every)
+				defer ticker.Stop()
 				for {
-					err := runner.fn(bot)
+					select {
+					case <-ctx.Done():
+						return
+					case <-ticker.C:
+					}
+					// When both ctx.Done() and ticker.C are ready at the same
+					// 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 := executeRunner(r, bot)
+					bot.safeEmitEvent(ctx, RunnerFinishedEvent{
+						Name:     r.name,
+						Duration: time.Since(startedAt),
+						Err:      err,
+					})
 					if err != nil {
-						bot.logger.Warnf("Runner %s failed: %s\n", runner.name, err)
+						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)
 					}
-					time.Sleep(runner.timeout)
 				}
-			}()
+			}(runner)
 		}
 	}
 }

runners_test.go

@@ -0,0 +1,124 @@
+package laniakea
+
+import (
+	"context"
+	"errors"
+	"sync/atomic"
+	"testing"
+	"time"
+
+	"git.scuroneko.dev/scuroneko/sneklog/v2"
+)
+
+type runnerObserver struct {
+	recordingObserver
+}
+
+func TestExecRunnersRunsOnceSyncRunner(t *testing.T) {
+	var calls atomic.Int32
+	bot := &Bot[NoData]{
+		logger: sneklog.NewLogger(),
+		runners: []Runner[NoData]{
+			NewRunner("sync-once", func(*Bot[NoData]) error {
+				calls.Add(1)
+				return nil
+			}).Async(false),
+		},
+	}
+
+	bot.ExecRunners(context.Background())
+
+	if got := calls.Load(); got != 1 {
+		t.Fatalf("unexpected sync runner call count: %d", got)
+	}
+}
+
+func TestExecRunnersStopsBackgroundRunnerOnCancel(t *testing.T) {
+	var calls atomic.Int32
+	triggered := make(chan struct{}, 1)
+	ctx, cancel := context.WithCancel(context.Background())
+
+	bot := &Bot[NoData]{
+		logger: sneklog.NewLogger(),
+		runners: []Runner[NoData]{
+			NewRunner("background", func(*Bot[NoData]) error {
+				if calls.Add(1) == 1 {
+					triggered <- struct{}{}
+				}
+				return nil
+			}).Every(5 * time.Millisecond),
+		},
+	}
+
+	bot.ExecRunners(ctx)
+
+	select {
+	case <-triggered:
+	case <-time.After(time.Second):
+		t.Fatal("background runner did not execute")
+	}
+
+	cancel()
+	bot.runnerBgWG.Wait()
+
+	if calls.Load() == 0 {
+		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)
+	}
+}
+
+func TestExecRunnersRecoversRunnerPanic(t *testing.T) {
+	observer := &runnerObserver{}
+	bot := &Bot[NoData]{
+		logger:   sneklog.NewLogger(),
+		observer: observer,
+		runners: []Runner[NoData]{
+			NewRunner("panic", func(*Bot[NoData]) error {
+				panic("boom")
+			}).Async(false),
+		},
+	}
+	defer func() {
+		if err := bot.logger.Close(); err != nil {
+			t.Fatalf("Close returned error: %v", err)
+		}
+	}()
+
+	bot.ExecRunners(context.Background())
+
+	if len(observer.runners) != 1 || observer.runners[0].Err == nil {
+		t.Fatalf("expected recovered panic in runner event, got %#v", observer.runners)
+	}
+	if len(observer.errors) != 1 || observer.errors[0].Err == nil {
+		t.Fatalf("expected recovered panic in error event, got %#v", observer.errors)
+	}
+}

scene.go

@@ -0,0 +1,269 @@
+package laniakea
+
+import (
+	"bytes"
+	"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 []byte
+}
+
+// SetData stores arbitrary opaque session data.
+func (s *SceneSession) SetData(data []byte) {
+	s.data = bytes.Clone(data)
+}
+
+// GetData returns the raw session data payload.
+func (s *SceneSession) GetData() []byte {
+	return bytes.Clone(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 {
+		session.data = bytes.Clone(session.data)
+		return session, nil
+	}
+	return SceneSession{}, nil
+}
+
+// Set stores session under key.
+func (s *MemorySessionStore) Set(key string, session SceneSession) error {
+	session.data = bytes.Clone(session.data)
+	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_locks.go

@@ -0,0 +1,80 @@
+package laniakea
+
+import (
+	"sort"
+	"sync"
+)
+
+type sceneLockEntry struct {
+	mu   sync.Mutex
+	refs int
+}
+
+type sceneKeyLocker struct {
+	mu      sync.Mutex
+	entries map[string]*sceneLockEntry
+}
+
+func (l *sceneKeyLocker) lock(keys []string) func() {
+	keys = uniqueSortedStrings(keys)
+	if len(keys) == 0 {
+		return func() {}
+	}
+
+	l.mu.Lock()
+	if l.entries == nil {
+		l.entries = make(map[string]*sceneLockEntry)
+	}
+	entries := make([]*sceneLockEntry, len(keys))
+	for i, key := range keys {
+		entry := l.entries[key]
+		if entry == nil {
+			entry = new(sceneLockEntry)
+			l.entries[key] = entry
+		}
+		entry.refs++
+		entries[i] = entry
+	}
+	l.mu.Unlock()
+
+	for _, entry := range entries {
+		entry.mu.Lock()
+	}
+
+	return func() {
+		for i := len(entries) - 1; i >= 0; i-- {
+			entries[i].mu.Unlock()
+		}
+
+		l.mu.Lock()
+		for i, key := range keys {
+			entries[i].refs--
+			if entries[i].refs == 0 {
+				delete(l.entries, key)
+			}
+		}
+		l.mu.Unlock()
+	}
+}
+
+func uniqueSortedStrings(values []string) []string {
+	sort.Strings(values)
+	result := values[:0]
+	for _, value := range values {
+		if value == "" || len(result) > 0 && result[len(result)-1] == value {
+			continue
+		}
+		result = append(result, value)
+	}
+	return result
+}
+
+func sceneKeysForContext(ctx *MessageContext) []string {
+	keys := make([]string, 0, 3)
+	for _, scope := range []SceneScope{SceneScopeUserChat, SceneScopeChat, SceneScopeUser} {
+		if key, ok := buildSceneKey(scope, ctx); ok {
+			keys = append(keys, key)
+		}
+	}
+	return keys
+}

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,129 +9,336 @@ import (
 	"net/http"
 	"time"
 
-	"git.nix13.pw/scuroneko/laniakea/utils"
-	"git.nix13.pw/scuroneko/slog"
+	"git.scuroneko.dev/scuroneko/laniakea/utils"
+	"git.scuroneko.dev/scuroneko/sneklog/v2"
 )
 
+// APIOpts holds configuration options for initializing the Telegram API client.
+// Use the provided setter methods to build options — do not construct directly.
 type APIOpts struct {
 	token         string
 	client        *http.Client
 	useTestServer bool
-	apiUrl        string
+	apiURL        string
+
+	logFormat    utils.LogFormat
+	logFormatter *sneklog.Formatter
+
+	limiter           *utils.RateLimiter
+	dropOverflowLimit bool
 }
 
+// NewAPIOpts creates a new APIOpts with default values.
+// Use setter methods to customize behavior.
 func NewAPIOpts(token string) *APIOpts {
-	return &APIOpts{token: token, client: nil, useTestServer: false, apiUrl: "https://api.telegram.org"}
+	return &APIOpts{
+		token:         token,
+		client:        nil,
+		useTestServer: false,
+		apiURL:        "https://api.telegram.org",
+	}
 }
+
+// SetHTTPClient sets a custom HTTP client. Use this for timeouts, proxies, or custom transport.
+// If not set, a default client with 45s timeout is used.
 func (opts *APIOpts) SetHTTPClient(client *http.Client) *APIOpts {
 	if client != nil {
 		opts.client = client
 	}
 	return opts
 }
+
+// UseTestServer enables use of Telegram's test server (https://api.test.telegram.org).
+// Only for development/testing.
 func (opts *APIOpts) UseTestServer(use bool) *APIOpts {
 	opts.useTestServer = use
 	return opts
 }
-func (opts *APIOpts) SetAPIUrl(apiUrl string) *APIOpts {
-	if apiUrl != "" {
-		opts.apiUrl = apiUrl
+
+// SetAPIURL overrides the default Telegram API URL.
+// Useful for self-hosted bots or proxies.
+func (opts *APIOpts) SetAPIURL(apiURL string) *APIOpts {
+	if apiURL != "" {
+		opts.apiURL = apiURL
 	}
 	return opts
 }
 
+// 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 {
+	opts.limiter = limiter
+	return opts
+}
+
+// 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) SetDropRateLimitOverflow(b bool) *APIOpts {
+	opts.dropOverflowLimit = b
+	return opts
+}
+
+// API is the main Telegram Bot API client for JSON requests.
+//
+// Use API methods when sending JSON payloads (for example with file_id, URL, or other
+// non-multipart fields). For multipart file uploads, use Uploader.
+//
+// It manages HTTP requests, rate limiting, retries, and connection pooling.
 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
+	dropOverflowLimit bool
 }
 
+// NewAPI creates a new API client from options.
+// Always call Close() when done to release resources.
 func NewAPI(opts *APIOpts) *API {
-	l := slog.CreateLogger().Level(utils.GetLoggerLevel()).Prefix("API")
-	l.AddWriter(l.CreateJsonStdoutWriter())
+	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 {
 		client = &http.Client{Timeout: time.Second * 45}
 	}
-	return &API{opts.token, client, l, opts.useTestServer, opts.apiUrl}
-}
-func (api *API) CloseApi() error         { return api.logger.Close() }
-func (api *API) GetLogger() *slog.Logger { return api.logger }
 
-type ApiResponse[R any] struct {
-	Ok          bool   `json:"ok"`
-	Description string `json:"description,omitempty"`
-	Result      R      `json:"result,omitempty"`
-	ErrorCode   int    `json:"error_code,omitempty"`
+	pool := newWorkerPool(16, 256)
+	pool.start()
+
+	return &API{
+		token:         opts.token,
+		client:        client,
+		logger:        logger,
+		useTestServer: opts.useTestServer,
+		apiURL:        opts.apiURL,
+
+		logFormat:    opts.logFormat,
+		logFormatter: opts.logFormatter,
+
+		pool:              pool,
+		Limiter:           opts.limiter,
+		dropOverflowLimit: opts.dropOverflowLimit,
+	}
 }
+
+// Close shuts down the internal worker pool and closes the logger.
+// Must be called to avoid resource leaks.
+// See https://core.telegram.org/bots/api
+func (api *API) Close() error {
+	api.pool.stop()
+	if api.client != nil {
+		api.client.CloseIdleConnections()
+	}
+	return api.logger.Close()
+}
+
+// GetLogger returns the internal logger for custom logging.
+// See https://core.telegram.org/bots/api
+func (api *API) GetLogger() *sneklog.Logger {
+	return api.logger
+}
+
+// ResponseParameters contains Telegram API response metadata (e.g., retry_after, migrate_to_chat_id).
+type ResponseParameters struct {
+	MigrateToChatID *int64 `json:"migrate_to_chat_id,omitempty"`
+	RetryAfter      *int   `json:"retry_after,omitempty"`
+}
+
+// TelegramResponse is the standard Telegram Bot API response structure.
+// Generic over Result type R.
+type TelegramResponse[R any] struct {
+	Ok          bool                `json:"ok"`
+	Description string              `json:"description,omitempty"`
+	Result      R                   `json:"result,omitempty"`
+	ErrorCode   int                 `json:"error_code,omitempty"`
+	Parameters  *ResponseParameters `json:"parameters,omitempty"`
+}
+
+// TelegramRequest is a low-level Telegram API request wrapper.
+//
+// Prefer method-specific helpers such as SendMessage or GetUpdates. TelegramRequest
+// bypasses method-specific parameter types and convenience helpers, so callers are
+// responsible for using the correct method name and compatible request and response types.
+// In that sense it is an unsafe escape hatch compared with the typed API surface.
 type TelegramRequest[R, P any] struct {
 	method string
 	params P
+	chatID int64
 }
 
+// NewRequest creates a low-level TelegramRequest with no associated chat ID.
 func NewRequest[R, P any](method string, params P) TelegramRequest[R, P] {
-	return TelegramRequest[R, P]{method: method, params: params}
+	return TelegramRequest[R, P]{method, params, 0}
 }
-func (r TelegramRequest[R, P]) DoWithContext(ctx context.Context, api *API) (R, error) {
+
+// 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] {
+	return TelegramRequest[R, P]{method, params, chatID}
+}
+
+func (r TelegramRequest[R, P]) doRequest(ctx context.Context, api *API) (R, error) {
 	var zero R
-	data, err := json.Marshal(r.params)
+	reqData, err := json.Marshal(r.params)
 	if err != nil {
-		return zero, err
+		return zero, fmt.Errorf("failed to marshal request: %w", err)
 	}
-	buf := bytes.NewBuffer(data)
 
 	methodPrefix := ""
 	if api.useTestServer {
 		methodPrefix = "/test"
 	}
-	url := fmt.Sprintf("%s/bot%s%s/%s", api.apiUrl, api.token, methodPrefix, r.method)
-	req, err := http.NewRequestWithContext(ctx, "POST", url, buf)
+	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, err
+		return zero, fmt.Errorf("failed to create request: %w", err)
 	}
+
 	req.Header.Set("Content-Type", "application/json")
 	req.Header.Set("Accept", "application/json")
 	req.Header.Set("User-Agent", fmt.Sprintf("Laniakea/%s", utils.VersionString))
 
-	api.logger.Debugln("REQ", api.apiUrl, r.method, buf.String())
-	res, err := api.client.Do(req)
-	if err != nil {
-		return zero, err
-	}
-	defer func(Body io.ReadCloser) {
-		_ = Body.Close()
-	}(res.Body)
+	for {
+		// Apply rate limiting before making the request
+		if api.Limiter != nil {
+			if err := api.Limiter.Check(ctx, api.dropOverflowLimit, r.chatID); err != nil {
+				return zero, err
+			}
+		}
+		buf := bytes.NewBuffer(reqData)
+		req.Body = io.NopCloser(buf)
+		req.ContentLength = int64(len(reqData))
 
-	data, err = readBody(res.Body)
-	if err != nil {
-		return zero, err
-	}
-	api.logger.Debugln("RES", r.method, string(data))
-	if res.StatusCode != http.StatusOK {
-		return zero, fmt.Errorf("unexpected status code: %d, %s", res.StatusCode, string(data))
-	}
-	return parseBody[R](data)
+		api.logger.Debugln("REQ", url, redactRequestLog(reqData))
+		resp, err := api.client.Do(req)
+		if err != nil {
+			return zero, fmt.Errorf("HTTP request failed: %w", err)
+		}
 
+		respData, err := readBody(resp.Body)
+		_ = resp.Body.Close() // ensure body is closed
+		if err != nil {
+			return zero, fmt.Errorf("failed to read response body: %w", err)
+		}
+
+		api.logger.Debugln("RES", responseLogSummary(r.method, len(respData)))
+
+		response, err := parseBody[R](respData)
+		if err != nil {
+			return zero, fmt.Errorf("failed to parse response: %w", err)
+		}
+
+		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)
+
+				// Apply cooldown to global or chat-specific limiter
+				if api.Limiter != nil {
+					if r.chatID != 0 {
+						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():
+					return zero, ctx.Err()
+				case <-time.After(time.Duration(after) * time.Second):
+					continue // retry request
+				}
+			}
+
+			// Other API errors
+			return zero, responseErr
+		}
+
+		return response.Result, nil
+	}
 }
+
+// DoWithContext executes the request asynchronously via the worker pool.
+// Returns result or error via channel. Respects context cancellation.
+func (r TelegramRequest[R, P]) DoWithContext(ctx context.Context, api *API) (R, error) {
+	var zero R
+
+	resultChan, err := api.pool.submit(ctx, func(ctx context.Context) (any, error) {
+		return r.doRequest(ctx, api)
+	})
+	if err != nil {
+		return zero, err
+	}
+
+	select {
+	case <-ctx.Done():
+		return zero, ctx.Err()
+	case res := <-resultChan:
+		if res.err != nil {
+			return zero, res.err
+		}
+		if val, ok := res.value.(R); ok {
+			return val, nil
+		}
+		return zero, ErrPoolUnexpected
+	}
+}
+
+// Do executes the request synchronously with a background context.
+// Use only for simple, non-critical calls.
 func (r TelegramRequest[R, P]) Do(api *API) (R, error) {
 	return r.DoWithContext(context.Background(), api)
 }
 
 func readBody(body io.ReadCloser) ([]byte, error) {
-	reader := io.LimitReader(body, 10<<20)
+	reader := io.LimitReader(body, 10<<20) // 10 MB
 	return io.ReadAll(reader)
 }
-func parseBody[R any](data []byte) (R, error) {
-	var zero R
-	var resp ApiResponse[R]
+
+func parseBody[R any](data []byte) (TelegramResponse[R], error) {
+	var resp TelegramResponse[R]
 	err := json.Unmarshal(data, &resp)
 	if err != nil {
-		return zero, err
+		return resp, fmt.Errorf("failed to unmarshal JSON: %w", err)
 	}
-	if !resp.Ok {
-		return zero, fmt.Errorf("[%d] %s", resp.ErrorCode, resp.Description)
-	}
-	return resp.Result, nil
+	return resp, nil
 }

tgapi/api101_test.go

@@ -0,0 +1,209 @@
+package tgapi
+
+import (
+	"encoding/json"
+	"strings"
+	"testing"
+)
+
+func TestEditMessageTextMarshalsInputRichMessage(t *testing.T) {
+	params := EditMessageText{
+		ChatID:    1,
+		MessageID: 2,
+		RichMessage: &InputRichMessage{
+			HTML:                "<p>hi</p>",
+			SkipEntityDetection: true,
+		},
+	}
+	data, err := json.Marshal(params)
+	if err != nil {
+		t.Fatalf("Marshal returned error: %v", err)
+	}
+	got := string(data)
+	for _, want := range []string{`"rich_message":{"html":`, `"skip_entity_detection":true`} {
+		if !strings.Contains(got, want) {
+			t.Fatalf("missing %s in editMessageText JSON: %s", want, got)
+		}
+	}
+	if strings.Contains(got, `"blocks"`) {
+		t.Fatalf("rich_message must be an InputRichMessage, not a block tree: %s", got)
+	}
+	if strings.Contains(got, `"text"`) {
+		t.Fatalf("empty text must be omitted when editing rich content: %s", got)
+	}
+}
+
+func TestSendRichMessageDraftMarshal(t *testing.T) {
+	params := SendRichMessageDraft{
+		ChatID:      1,
+		DraftID:     7,
+		RichMessage: InputRichMessage{Markdown: "*hi*"},
+	}
+	data, err := json.Marshal(params)
+	if err != nil {
+		t.Fatalf("Marshal returned error: %v", err)
+	}
+	got := string(data)
+	for _, want := range []string{`"chat_id":1`, `"draft_id":7`, `"rich_message":{"markdown":"*hi*"}`} {
+		if !strings.Contains(got, want) {
+			t.Fatalf("missing %s in sendRichMessageDraft JSON: %s", want, got)
+		}
+	}
+}
+
+func TestInputRichMessageContentMarshal(t *testing.T) {
+	content := InputRichMessageContent{
+		RichMessage: InputRichMessage{HTML: "<p>hi</p>"},
+	}
+	data, err := json.Marshal(content)
+	if err != nil {
+		t.Fatalf("Marshal returned error: %v", err)
+	}
+	if got := string(data); !strings.Contains(got, `"rich_message":{"html":`) {
+		t.Fatalf("unexpected InputRichMessageContent JSON: %s", got)
+	}
+}
+
+func TestInputRichMessageMediaMarshal(t *testing.T) {
+	message := InputRichMessage{
+		HTML: `<video src="tg://video?id=intro"></video>`,
+		Media: []InputRichMessageMedia{{
+			ID:    "intro",
+			Media: InputMedia{Type: InputMediaTypeVideo, Media: "attach://intro"},
+		}},
+	}
+	data, err := json.Marshal(message)
+	if err != nil {
+		t.Fatalf("Marshal returned error: %v", err)
+	}
+
+	var got struct {
+		Media []struct {
+			ID    string     `json:"id"`
+			Media InputMedia `json:"media"`
+		} `json:"media"`
+	}
+	if err := json.Unmarshal(data, &got); err != nil {
+		t.Fatalf("Unmarshal returned error: %v", err)
+	}
+	if len(got.Media) != 1 || got.Media[0].ID != "intro" {
+		t.Fatalf("unexpected media: %+v", got.Media)
+	}
+	if got.Media[0].Media.Type != InputMediaTypeVideo || got.Media[0].Media.Media != "attach://intro" {
+		t.Fatalf("unexpected embedded media: %+v", got.Media[0].Media)
+	}
+}
+
+func TestEphemeralMethodsMarshalReceiverUserID(t *testing.T) {
+	cases := []struct {
+		name   string
+		params any
+	}{
+		{"edit text", EditEphemeralMessageText{ChatID: 1, ReceiverUserID: 2, EphemeralMessageID: 3, Text: "updated"}},
+		{"edit media", EditEphemeralMessageMedia{ChatID: 1, ReceiverUserID: 2, EphemeralMessageID: 3, Media: InputMedia{Type: InputMediaTypePhoto, Media: "photo-id"}}},
+		{"edit caption", EditEphemeralMessageCaption{ChatID: 1, ReceiverUserID: 2, EphemeralMessageID: 3, Caption: "updated"}},
+		{"edit markup", EditEphemeralMessageReplyMarkup{ChatID: 1, ReceiverUserID: 2, EphemeralMessageID: 3}},
+		{"delete", DeleteEphemeralMessage{ChatID: 1, ReceiverUserID: 2, EphemeralMessageID: 3}},
+	}
+
+	for _, tt := range cases {
+		t.Run(tt.name, func(t *testing.T) {
+			data, err := json.Marshal(tt.params)
+			if err != nil {
+				t.Fatalf("Marshal returned error: %v", err)
+			}
+			var fields map[string]json.RawMessage
+			if err := json.Unmarshal(data, &fields); err != nil {
+				t.Fatalf("Unmarshal returned error: %v", err)
+			}
+			if _, ok := fields["receiver_user_id"]; !ok {
+				t.Fatalf("receiver_user_id is missing from %s", data)
+			}
+			if _, ok := fields["reciever_user_id"]; ok {
+				t.Fatalf("misspelled receiver_user_id is present in %s", data)
+			}
+		})
+	}
+}
+
+func TestEphemeralSendParametersMarshal(t *testing.T) {
+	cases := []struct {
+		name   string
+		params any
+	}{
+		{"message", SendMessage{ChatID: 1, Text: "text", ReceiverUserID: 2, CallbackQueryID: "callback"}},
+		{"animation", SendAnimation{ChatID: 1, Animation: "animation", ReceiverUserID: 2, CallbackQueryID: "callback"}},
+		{"audio", SendAudio{ChatID: 1, Audio: "audio", ReceiverUserID: 2, CallbackQueryID: "callback"}},
+		{"document", SendDocument{ChatID: 1, Document: "document", ReceiverUserID: 2, CallbackQueryID: "callback"}},
+		{"photo", SendPhoto{ChatID: 1, Photo: "photo", ReceiverUserID: 2, CallbackQueryID: "callback"}},
+		{"sticker", SendSticker{ChatID: 1, Sticker: "sticker", ReceiverUserID: 2, CallbackQueryID: "callback"}},
+		{"video", SendVideo{ChatID: 1, Video: "video", ReceiverUserID: 2, CallbackQueryID: "callback"}},
+		{"video note", SendVideoNote{ChatID: 1, VideoNote: "video-note", ReceiverUserID: 2, CallbackQueryID: "callback"}},
+		{"voice", SendVoice{ChatID: 1, Voice: "voice", ReceiverUserID: 2, CallbackQueryID: "callback"}},
+		{"contact", SendContact{ChatID: 1, PhoneNumber: "+10000000000", FirstName: "A", ReceiverUserID: 2, CallbackQueryID: "callback"}},
+		{"location", SendLocation{ChatID: 1, Latitude: 1, Longitude: 2, ReceiverUserID: 2, CallbackQueryID: "callback"}},
+		{"venue", SendVenue{ChatID: 1, Latitude: 1, Longitude: 2, Title: "Venue", Address: "Address", ReceiverUserID: 2, CallbackQueryID: "callback"}},
+	}
+
+	for _, tt := range cases {
+		t.Run(tt.name, func(t *testing.T) {
+			data, err := json.Marshal(tt.params)
+			if err != nil {
+				t.Fatalf("Marshal returned error: %v", err)
+			}
+			if !strings.Contains(string(data), `"receiver_user_id":2`) || !strings.Contains(string(data), `"callback_query_id":"callback"`) {
+				t.Fatalf("missing ephemeral parameters in %s", data)
+			}
+		})
+	}
+}
+
+func TestInputPollOptionMediaLinkMarshal(t *testing.T) {
+	media := InputPollOptionMedia{Type: "link", URL: "https://example.com"}
+	data, err := json.Marshal(media)
+	if err != nil {
+		t.Fatalf("Marshal returned error: %v", err)
+	}
+	got := string(data)
+	if got != `{"type":"link","url":"https://example.com"}` {
+		t.Fatalf("unexpected link media JSON: %s", got)
+	}
+}
+
+func TestPollMediaUnmarshalLink(t *testing.T) {
+	var media PollMedia
+	if err := json.Unmarshal([]byte(`{"link":{"url":"https://example.com"}}`), &media); err != nil {
+		t.Fatalf("Unmarshal returned error: %v", err)
+	}
+	if media.Link == nil || media.Link.URL != "https://example.com" {
+		t.Fatalf("unexpected poll media link: %+v", media.Link)
+	}
+}
+
+func TestChatJoinRequestUnmarshalQueryID(t *testing.T) {
+	payload := `{"chat":{"id":1},"from":{"id":2,"first_name":"A"},"user_chat_id":2,"date":3,"query_id":"q42"}`
+	var req ChatJoinRequest
+	if err := json.Unmarshal([]byte(payload), &req); err != nil {
+		t.Fatalf("Unmarshal returned error: %v", err)
+	}
+	if req.QueryID == nil || *req.QueryID != "q42" {
+		t.Fatalf("unexpected query_id: %+v", req.QueryID)
+	}
+}
+
+func TestAnswerChatJoinRequestQueryResultValues(t *testing.T) {
+	if JoinRequestApprove != "approve" || JoinRequestDecline != "decline" || JoinRequestQueue != "queue" {
+		t.Fatalf("unexpected join request query result values: %q %q %q",
+			JoinRequestApprove, JoinRequestDecline, JoinRequestQueue)
+	}
+}
+
+func TestUserUnmarshalSupportsJoinRequestQueries(t *testing.T) {
+	var user User
+	if err := json.Unmarshal([]byte(`{"id":1,"first_name":"A","supports_join_request_queries":true}`), &user); err != nil {
+		t.Fatalf("Unmarshal returned error: %v", err)
+	}
+	if user.SupportsJoinRequestQueries == nil || !*user.SupportsJoinRequestQueries {
+		t.Fatalf("unexpected supports_join_request_queries: %+v", user.SupportsJoinRequestQueries)
+	}
+}

tgapi/api_test.go

@@ -0,0 +1,90 @@
+package tgapi
+
+import (
+	"io"
+	"net/http"
+	"strings"
+	"testing"
+)
+
+type roundTripFunc func(*http.Request) (*http.Response, error)
+
+func (fn roundTripFunc) RoundTrip(req *http.Request) (*http.Response, error) {
+	return fn(req)
+}
+
+type closingTransport struct {
+	roundTripFunc
+	closed bool
+}
+
+func (t *closingTransport) CloseIdleConnections() {
+	t.closed = true
+}
+
+func TestAPILeavesAcceptEncodingToHTTPTransport(t *testing.T) {
+	var gotPath string
+	var gotAcceptEncoding string
+
+	client := &http.Client{
+		Transport: roundTripFunc(func(req *http.Request) (*http.Response, error) {
+			gotPath = req.URL.Path
+			gotAcceptEncoding = req.Header.Get("Accept-Encoding")
+			return &http.Response{
+				StatusCode: http.StatusOK,
+				Header:     http.Header{"Content-Type": []string{"application/json"}},
+				Body:       io.NopCloser(strings.NewReader(`{"ok":true,"result":{"id":1,"is_bot":true,"first_name":"Test"}}`)),
+			}, 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)
+		}
+	}()
+
+	user, err := api.GetMe()
+	if err != nil {
+		t.Fatalf("GetMe returned error: %v", err)
+	}
+	if user.FirstName != "Test" {
+		t.Fatalf("unexpected first name: %q", user.FirstName)
+	}
+	if gotPath != "/bottoken/getMe" {
+		t.Fatalf("unexpected request path: %s", gotPath)
+	}
+	if gotAcceptEncoding != "" {
+		t.Fatalf("expected empty Accept-Encoding header, got %q", gotAcceptEncoding)
+	}
+}
+
+func TestAPICloseClosesIdleConnections(t *testing.T) {
+	transport := &closingTransport{
+		roundTripFunc: 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":{"id":1,"is_bot":true,"first_name":"Test"}}`)),
+			}, nil
+		},
+	}
+
+	api := NewAPI(
+		NewAPIOpts("token").
+			SetAPIURL("https://example.test").
+			SetHTTPClient(&http.Client{Transport: transport}),
+	)
+
+	if err := api.Close(); err != nil {
+		t.Fatalf("Close returned error: %v", err)
+	}
+	if !transport.closed {
+		t.Fatal("expected Close to close idle HTTP connections")
+	}
+}

tgapi/attachments_methods.go

@@ -1,10 +1,19 @@
 package tgapi
 
-type SendPhotoP struct {
+import "context"
+
+// SendPhoto holds parameters for the sendPhoto method.
+// Since: Bot API 1.0
+// See https://core.telegram.org/bots/api#sendphoto
+type SendPhoto struct {
 	BusinessConnectionID  string `json:"business_connection_id,omitempty"`
-	ChatID                int    `json:"chat_id"`
+	ChatID                int64  `json:"chat_id"`
 	MessageThreadID       int    `json:"message_thread_id,omitempty"`
 	DirectMessagesTopicID int    `json:"direct_messages_topic_id,omitempty"`
+	// ReceiverUserID identifies the user who can see the ephemeral message.
+	ReceiverUserID int64 `json:"receiver_user_id,omitempty"` // Since: Bot API 10.2
+	// CallbackQueryID identifies the callback query that triggered an ephemeral response.
+	CallbackQueryID string `json:"callback_query_id,omitempty"` // Since: Bot API 10.2
 
 	Photo           string          `json:"photo"`
 	Caption         string          `json:"caption,omitempty"`
@@ -13,7 +22,7 @@ type SendPhotoP struct {
 
 	ShowCaptionAboveMedia bool   `json:"show_caption_above_media,omitempty"`
 	HasSpoiler            bool   `json:"has_spoiler,omitempty"`
-	DisableNotifications  bool   `json:"disable_notifications,omitempty"`
+	DisableNotifications  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"`
@@ -23,16 +32,35 @@ type SendPhotoP struct {
 	ReplyMarkup             *ReplyMarkup             `json:"reply_markup,omitempty"`
 }
 
-func (api *API) SendPhoto(params SendPhotoP) (Message, error) {
-	req := NewRequest[Message]("sendPhoto", params)
+// SendPhoto sends a photo.
+// Since: Bot API 1.0
+// See https://core.telegram.org/bots/api#sendphoto
+func (api *API) SendPhoto(params SendPhoto) (Message, error) {
+	req := NewRequestWithChatID[Message]("sendPhoto", params, params.ChatID)
 	return req.Do(api)
 }
 
-type SendAudioP struct {
+// 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 SendPhoto) (Message, error) {
+	req := NewRequestWithChatID[Message]("sendPhoto", params, params.ChatID)
+	return req.DoWithContext(ctx, api)
+}
+
+// SendAudio holds parameters for the sendAudio method.
+// Since: Bot API 1.2
+// See https://core.telegram.org/bots/api#sendaudio
+type SendAudio struct {
 	BusinessConnectionID  string `json:"business_connection_id,omitempty"`
-	ChatID                int    `json:"chat_id"`
+	ChatID                int64  `json:"chat_id"`
 	MessageThreadID       int    `json:"message_thread_id,omitempty"`
 	DirectMessagesTopicID int    `json:"direct_messages_topic_id,omitempty"`
+	// ReceiverUserID identifies the user who can see the ephemeral message.
+	ReceiverUserID int64 `json:"receiver_user_id,omitempty"` // Since: Bot API 10.2
+	// CallbackQueryID identifies the callback query that triggered an ephemeral response.
+	CallbackQueryID string `json:"callback_query_id,omitempty"` // Since: Bot API 10.2
 
 	Audio           string          `json:"audio"`
 	Caption         string          `json:"caption,omitempty"`
@@ -41,6 +69,7 @@ type SendAudioP struct {
 	Duration        int             `json:"duration,omitempty"`
 	Performer       string          `json:"performer,omitempty"`
 	Title           string          `json:"title,omitempty"`
+	Thumbnail       string          `json:"thumbnail,omitempty"`
 
 	DisableNotification bool   `json:"disable_notification,omitempty"`
 	ProtectContent      bool   `json:"protect_content,omitempty"`
@@ -52,21 +81,42 @@ type SendAudioP struct {
 	ReplyMarkup             *ReplyMarkup             `json:"reply_markup,omitempty"`
 }
 
-func (api *API) SendAudio(params SendAudioP) (Message, error) {
-	req := NewRequest[Message]("sendAudio", params)
+// SendAudio sends an audio file.
+// Since: Bot API 1.2
+// See https://core.telegram.org/bots/api#sendaudio
+func (api *API) SendAudio(params SendAudio) (Message, error) {
+	req := NewRequestWithChatID[Message]("sendAudio", params, params.ChatID)
 	return req.Do(api)
 }
 
-type SendDocumentP struct {
+// 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 SendAudio) (Message, error) {
+	req := NewRequestWithChatID[Message]("sendAudio", params, params.ChatID)
+	return req.DoWithContext(ctx, api)
+}
+
+// SendDocument holds parameters for the sendDocument method.
+// Since: Bot API 1.0
+// See https://core.telegram.org/bots/api#senddocument
+type SendDocument struct {
 	BusinessConnectionID  string `json:"business_connection_id,omitempty"`
-	ChatID                int    `json:"chat_id"`
+	ChatID                int64  `json:"chat_id"`
 	MessageThreadID       int    `json:"message_thread_id,omitempty"`
 	DirectMessagesTopicID int    `json:"direct_messages_topic_id,omitempty"`
+	// ReceiverUserID identifies the user who can see the ephemeral message.
+	ReceiverUserID int64 `json:"receiver_user_id,omitempty"` // Since: Bot API 10.2
+	// CallbackQueryID identifies the callback query that triggered an ephemeral response.
+	CallbackQueryID string `json:"callback_query_id,omitempty"` // Since: Bot API 10.2
 
-	Document        string          `json:"document"`
-	Caption         string          `json:"caption,omitempty"`
-	ParseMode       ParseMode       `json:"parse_mode,omitempty"`
-	CaptionEntities []MessageEntity `json:"caption_entities,omitempty"`
+	Document                    string          `json:"document"`
+	Thumbnail                   string          `json:"thumbnail,omitempty"`
+	Caption                     string          `json:"caption,omitempty"`
+	ParseMode                   ParseMode       `json:"parse_mode,omitempty"`
+	CaptionEntities             []MessageEntity `json:"caption_entities,omitempty"`
+	DisableContentTypeDetection bool            `json:"disable_content_type_detection,omitempty"`
 
 	DisableNotification bool   `json:"disable_notification,omitempty"`
 	ProtectContent      bool   `json:"protect_content,omitempty"`
@@ -78,22 +128,42 @@ type SendDocumentP struct {
 	ReplyMarkup             *ReplyMarkup             `json:"reply_markup,omitempty"`
 }
 
-func (api *API) SendDocument(params SendDocumentP) (Message, error) {
-	req := NewRequest[Message]("sendDocument", params)
+// SendDocument sends a document.
+// Since: Bot API 1.0
+// See https://core.telegram.org/bots/api#senddocument
+func (api *API) SendDocument(params SendDocument) (Message, error) {
+	req := NewRequestWithChatID[Message]("sendDocument", params, params.ChatID)
 	return req.Do(api)
 }
 
-type SendVideoP struct {
+// 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 SendDocument) (Message, error) {
+	req := NewRequestWithChatID[Message]("sendDocument", params, params.ChatID)
+	return req.DoWithContext(ctx, api)
+}
+
+// SendVideo holds parameters for the sendVideo method.
+// Since: Bot API 1.0
+// See https://core.telegram.org/bots/api#sendvideo
+type SendVideo struct {
 	BusinessConnectionID  string `json:"business_connection_id,omitempty"`
-	ChatID                int    `json:"chat_id"`
+	ChatID                int64  `json:"chat_id"`
 	MessageThreadID       int    `json:"message_thread_id,omitempty"`
 	DirectMessagesTopicID int    `json:"direct_messages_topic_id,omitempty"`
+	// ReceiverUserID identifies the user who can see the ephemeral message.
+	ReceiverUserID int64 `json:"receiver_user_id,omitempty"` // Since: Bot API 10.2
+	// CallbackQueryID identifies the callback query that triggered an ephemeral response.
+	CallbackQueryID string `json:"callback_query_id,omitempty"` // Since: Bot API 10.2
 
-	Video    string `json:"video"`
-	Duration int    `json:"duration,omitempty"`
-	Width    int    `json:"width,omitempty"`
-	Height   int    `json:"height,omitempty"`
-	Cover    int    `json:"cover,omitempty"`
+	Video     string `json:"video"`
+	Thumbnail string `json:"thumbnail,omitempty"`
+	Duration  int    `json:"duration,omitempty"`
+	Width     int    `json:"width,omitempty"`
+	Height    int    `json:"height,omitempty"`
+	Cover     string `json:"cover,omitempty"`
 
 	StartTimestamp  int             `json:"start_timestamp,omitempty"`
 	Caption         string          `json:"caption,omitempty"`
@@ -113,18 +183,38 @@ type SendVideoP struct {
 	ReplyMarkup             *ReplyMarkup             `json:"reply_markup,omitempty"`
 }
 
-func (api *API) SendVideo(params SendVideoP) (Message, error) {
-	req := NewRequest[Message]("sendVideo", params)
+// SendVideo sends a video.
+// Since: Bot API 1.0
+// See https://core.telegram.org/bots/api#sendvideo
+func (api *API) SendVideo(params SendVideo) (Message, error) {
+	req := NewRequestWithChatID[Message]("sendVideo", params, params.ChatID)
 	return req.Do(api)
 }
 
-type SendAnimationP struct {
+// 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 SendVideo) (Message, error) {
+	req := NewRequestWithChatID[Message]("sendVideo", params, params.ChatID)
+	return req.DoWithContext(ctx, api)
+}
+
+// SendAnimation holds parameters for the sendAnimation method.
+// Since: Bot API 4.0
+// See https://core.telegram.org/bots/api#sendanimation
+type SendAnimation struct {
 	BusinessConnectionID  string `json:"business_connection_id,omitempty"`
-	ChatID                int    `json:"chat_id"`
+	ChatID                int64  `json:"chat_id"`
 	MessageThreadID       int    `json:"message_thread_id,omitempty"`
 	DirectMessagesTopicID int    `json:"direct_messages_topic_id,omitempty"`
+	// ReceiverUserID identifies the user who can see the ephemeral message.
+	ReceiverUserID int64 `json:"receiver_user_id,omitempty"` // Since: Bot API 10.2
+	// CallbackQueryID identifies the callback query that triggered an ephemeral response.
+	CallbackQueryID string `json:"callback_query_id,omitempty"` // Since: Bot API 10.2
 
 	Animation string `json:"animation"`
+	Thumbnail string `json:"thumbnail,omitempty"`
 	Duration  int    `json:"duration,omitempty"`
 	Width     int    `json:"width,omitempty"`
 	Height    int    `json:"height,omitempty"`
@@ -144,16 +234,35 @@ type SendAnimationP struct {
 	ReplyMarkup             *ReplyMarkup             `json:"reply_markup,omitempty"`
 }
 
-func (api *API) SendAnimation(params SendAnimationP) (Message, error) {
-	req := NewRequest[Message]("sendAnimation", params)
+// 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 SendAnimation) (Message, error) {
+	req := NewRequestWithChatID[Message]("sendAnimation", params, params.ChatID)
 	return req.Do(api)
 }
 
-type SendVoiceP struct {
+// 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 SendAnimation) (Message, error) {
+	req := NewRequestWithChatID[Message]("sendAnimation", params, params.ChatID)
+	return req.DoWithContext(ctx, api)
+}
+
+// SendVoice holds parameters for the sendVoice method.
+// Since: Bot API 1.2
+// See https://core.telegram.org/bots/api#sendvoice
+type SendVoice struct {
 	BusinessConnectionID  string `json:"business_connection_id,omitempty"`
-	ChatID                int    `json:"chat_id"`
+	ChatID                int64  `json:"chat_id"`
 	MessageThreadID       int    `json:"message_thread_id,omitempty"`
 	DirectMessagesTopicID int    `json:"direct_messages_topic_id,omitempty"`
+	// ReceiverUserID identifies the user who can see the ephemeral message.
+	ReceiverUserID int64 `json:"receiver_user_id,omitempty"` // Since: Bot API 10.2
+	// CallbackQueryID identifies the callback query that triggered an ephemeral response.
+	CallbackQueryID string `json:"callback_query_id,omitempty"` // Since: Bot API 10.2
 
 	Voice               string          `json:"voice"`
 	Caption             string          `json:"caption,omitempty"`
@@ -170,18 +279,38 @@ type SendVoiceP struct {
 	ReplyMarkup             *ReplyMarkup             `json:"reply_markup,omitempty"`
 }
 
-func (api *API) SendVoice(params *SendVoiceP) (Message, error) {
-	req := NewRequest[Message]("sendVoice", params)
+// SendVoice sends a voice note.
+// Since: Bot API 1.2
+// See https://core.telegram.org/bots/api#sendvoice
+func (api *API) SendVoice(params SendVoice) (Message, error) {
+	req := NewRequestWithChatID[Message]("sendVoice", params, params.ChatID)
 	return req.Do(api)
 }
 
-type SendVideoNoteP struct {
+// 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 SendVoice) (Message, error) {
+	req := NewRequestWithChatID[Message]("sendVoice", params, params.ChatID)
+	return req.DoWithContext(ctx, api)
+}
+
+// SendVideoNote holds parameters for the sendVideoNote method.
+// Since: Bot API 3.0
+// See https://core.telegram.org/bots/api#sendvideonote
+type SendVideoNote struct {
 	BusinessConnectionID  string `json:"business_connection_id,omitempty"`
-	ChatID                int    `json:"chat_id"`
+	ChatID                int64  `json:"chat_id"`
 	MessageThreadID       int    `json:"message_thread_id,omitempty"`
 	DirectMessagesTopicID int    `json:"direct_messages_topic_id,omitempty"`
+	// ReceiverUserID identifies the user who can see the ephemeral message.
+	ReceiverUserID int64 `json:"receiver_user_id,omitempty"` // Since: Bot API 10.2
+	// CallbackQueryID identifies the callback query that triggered an ephemeral response.
+	CallbackQueryID string `json:"callback_query_id,omitempty"` // Since: Bot API 10.2
 
 	VideoNote           string `json:"video_note"`
+	Thumbnail           string `json:"thumbnail,omitempty"`
 	Duration            int    `json:"duration,omitempty"`
 	Length              int    `json:"length,omitempty"`
 	DisableNotification bool   `json:"disable_notification,omitempty"`
@@ -194,14 +323,29 @@ type SendVideoNoteP struct {
 	ReplyMarkup             *ReplyMarkup             `json:"reply_markup,omitempty"`
 }
 
-func (api *API) SendVideoNote(params SendVideoNoteP) (Message, error) {
-	req := NewRequest[Message]("sendVideoNote", params)
+// 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 SendVideoNote) (Message, error) {
+	req := NewRequestWithChatID[Message]("sendVideoNote", params, params.ChatID)
 	return req.Do(api)
 }
 
-type SendPaidMediaP struct {
+// 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 SendVideoNote) (Message, error) {
+	req := NewRequestWithChatID[Message]("sendVideoNote", params, params.ChatID)
+	return req.DoWithContext(ctx, api)
+}
+
+// SendPaidMedia holds parameters for the sendPaidMedia method.
+// Since: Bot API 7.6
+// See https://core.telegram.org/bots/api#sendpaidmedia
+type SendPaidMedia struct {
 	BusinessConnectionID  string `json:"business_connection_id,omitempty"`
-	ChatID                int    `json:"chat_id"`
+	ChatID                int64  `json:"chat_id"`
 	MessageThreadID       int    `json:"message_thread_id,omitempty"`
 	DirectMessagesTopicID int    `json:"direct_messages_topic_id,omitempty"`
 	StarCount             int    `json:"star_count,omitempty"`
@@ -221,14 +365,29 @@ type SendPaidMediaP struct {
 	ReplyMarkup             *ReplyMarkup             `json:"reply_markup,omitempty"`
 }
 
-func (api *API) SendPaidMedia(params SendPaidMediaP) (Message, error) {
-	req := NewRequest[Message]("sendPaidMedia", params)
+// SendPaidMedia sends paid media.
+// Since: Bot API 7.6
+// See https://core.telegram.org/bots/api#sendpaidmedia
+func (api *API) SendPaidMedia(params SendPaidMedia) (Message, error) {
+	req := NewRequestWithChatID[Message]("sendPaidMedia", params, params.ChatID)
 	return req.Do(api)
 }
 
-type SendMediaGroupP struct {
+// 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 SendPaidMedia) (Message, error) {
+	req := NewRequestWithChatID[Message]("sendPaidMedia", params, params.ChatID)
+	return req.DoWithContext(ctx, api)
+}
+
+// SendMediaGroup holds parameters for the sendMediaGroup method.
+// Since: Bot API 3.5
+// See https://core.telegram.org/bots/api#sendmediagroup
+type SendMediaGroup struct {
 	BusinessConnectionID  string `json:"business_connection_id,omitempty"`
-	ChatID                int    `json:"chat_id"`
+	ChatID                int64  `json:"chat_id"`
 	MessageThreadID       int    `json:"message_thread_id,omitempty"`
 	DirectMessagesTopicID int    `json:"direct_messages_topic_id,omitempty"`
 
@@ -240,7 +399,68 @@ type SendMediaGroupP struct {
 	ReplyParameters     *ReplyParameters `json:"reply_parameters,omitempty"`
 }
 
-func (api *API) SendMediaGroup(params SendMediaGroupP) (Message, error) {
-	req := NewRequest[Message]("sendMediaGroup", params)
+// 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 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 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"`
+
+	// ReceiverUserID identifies the user who can see the ephemeral message.
+	ReceiverUserID int64 `json:"receiver_user_id,omitempty"` // Since: Bot API 10.2
+	// CallbackQueryID identifies the callback query that triggered an ephemeral response.
+	CallbackQueryID string `json:"callback_query_id,omitempty"` // Since: Bot API 10.2
+	LivePhoto       string `json:"live_photo"`
+	// Photo contains or identifies the associated photo.
+	Photo           string          `json:"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,382 @@
 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 identifies a paid-media preview.
+	PaidMediaPreviewType PaidMediaType = "preview"
+	// PaidMediaPhotoType identifies a paid photo.
+	PaidMediaPhotoType PaidMediaType = "photo"
+	// PaidMediaVideoType identifies a paid video.
+	PaidMediaVideoType PaidMediaType = "video"
+	// PaidMediaLivePhotoType identifies a paid live photo.
+	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.
+// For type "link" set URL instead of Media.
+// Since: Bot API 10.0
+// See https://core.telegram.org/bots/api#inputpolloptionmedia
+type InputPollOptionMedia struct {
+	Type  string `json:"type"`
+	Media string `json:"media,omitempty"`
+	// URL contains the HTTP URL.
+	URL string `json:"url,omitempty"` // Since: Bot API 10.1; for type "link"
+}
+
+// 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,omitempty"` // Since: Bot API 6.8
+	User                User     `json:"user,omitempty"`       // FIXME: Pointer in v2
+	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
+}
+
+// Link represents an HTTP link.
+// Since: Bot API 10.1
+// See https://core.telegram.org/bots/api#link
+type Link struct {
+	// URL contains the HTTP URL.
+	URL string `json:"url"`
+}
+
+// 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"`
+	// Link contains link media attached to the poll.
+	Link      *Link       `json:"link,omitempty"` // Since: Bot API 10.1
+	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
+
+const (
+	// InputMediaTypeAnimation is a GIF or H.264/MPEG-4 AVC video without sound.
+	InputMediaTypeAnimation InputMediaType = "animation"
+	// InputMediaTypeDocument is a general file.
+	InputMediaTypeDocument InputMediaType = "document"
+	// InputMediaTypePhoto is a photo.
+	InputMediaTypePhoto InputMediaType = "photo"
+	// InputMediaTypeVideo is a video.
+	InputMediaTypeVideo InputMediaType = "video"
+	// InputMediaTypeAudio is an audio file.
+	InputMediaTypeAudio InputMediaType = "audio"
+	// InputMediaTypeVoiceNote is a voice message.
+	//
+	// Since: Bot API 10.2
+	InputMediaTypeVoiceNote InputMediaType = "voice_note"
+
+	// InputMediaTypeSticker is a sticker.
+	InputMediaTypeSticker InputMediaType = "sticker"
+	// InputMediaTypeLocation is a location.
+	InputMediaTypeLocation InputMediaType = "location"
+	// InputMediaTypeVenue is a venue.
+	InputMediaTypeVenue InputMediaType = "venue"
+	// InputMediaTypeLivePhoto is a live photo.
+	InputMediaTypeLivePhoto InputMediaType = "live_photo" // Since: Bot API 10.0
+)
+
+// InputMedia represents the content of a media message to be sent.
+// Since: Bot API 4.0
+// See https://core.telegram.org/bots/api#inputmedia
 type InputMedia struct {
 	Type  InputMediaType `json:"type"`
 	Media string         `json:"media"`
@@ -7,11 +384,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"`
-	HasSpoiler            *bool           `json:"has_spoiler,omitempty"`
+	ShowCaptionAboveMedia *bool           `json:"show_caption_above_media,omitempty"` // Since: Bot API 7.4
+	HasSpoiler            *bool           `json:"has_spoiler,omitempty"`              // Since: Bot API 6.4
 
-	Cover             *string `json:"cover"`
-	StartTimestamp    *int    `json:"start_timestamp"`
+	Cover             *string `json:"cover"`           // Since: Bot API 8.3
+	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"`
@@ -19,41 +396,67 @@ 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"`
 }
 
-type InputMediaType string
-
-const (
-	InputMediaTypeAnimation InputMediaType = "animation"
-	InputMediaTypeDocument  InputMediaType = "document"
-	InputMediaTypePhoto     InputMediaType = "photo"
-	InputMediaTypeVideo     InputMediaType = "video"
-	InputMediaTypeAudio     InputMediaType = "audio"
-)
-
+// InputPaidMediaType represents the type of paid media.
 type InputPaidMediaType string
 
 const (
+	// InputPaidMediaTypeVideo represents a paid video.
 	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"`
-	StartTimestamp    int64  `json:"start_timestamp"`
-	Width             int    `json:"width"`
-	Height            int    `json:"height"`
-	Duration          int    `json:"duration"`
-	SupportsStreaming bool   `json:"supports_streaming"`
+	Cover             *string `json:"cover,omitempty"`           // Since: Bot API 8.3
+	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"`
+	SupportsStreaming *bool   `json:"supports_streaming,omitempty"`
 }
 
+// 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"`
 	FileUniqueID string `json:"file_unique_id"`
 	Width        int    `json:"width"`
 	Height       int    `json:"height"`
-	FileSize     int    `json:"file_size,omitempty"`
+	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

@@ -1,152 +1,401 @@
 package tgapi
 
-type SetMyCommandsP struct {
+import "context"
+
+// SetMyCommands holds parameters for the setMyCommands method.
+// Since: Bot API 4.7
+// See https://core.telegram.org/bots/api#setmycommands
+type SetMyCommands struct {
 	Commands []BotCommand     `json:"commands"`
 	Scope    *BotCommandScope `json:"scope,omitempty"`
 	Language string           `json:"language_code,omitempty"`
 }
 
-func (api *API) SetMyCommands(params SetMyCommandsP) (bool, error) {
+// 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 SetMyCommands) (bool, error) {
 	req := NewRequest[bool]("setMyCommands", params)
 	return req.Do(api)
 }
 
-type DeleteMyCommandsP struct {
+// 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 SetMyCommands) (bool, error) {
+	req := NewRequest[bool]("setMyCommands", params)
+	return req.DoWithContext(ctx, api)
+}
+
+// DeleteMyCommands holds parameters for the deleteMyCommands method.
+// Since: Bot API 5.3
+// See https://core.telegram.org/bots/api#deletemycommands
+type DeleteMyCommands struct {
 	Scope    *BotCommandScope `json:"scope,omitempty"`
 	Language string           `json:"language_code,omitempty"`
 }
 
-func (api *API) DeleteMyCommands(params DeleteMyCommandsP) (bool, error) {
+// 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 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 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"`
 	Language string           `json:"language_code,omitempty"`
 }
 
+// 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)
 	return req.Do(api)
 }
 
+// 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) {
+	req := NewRequest[[]BotCommand]("getMyCommands", params)
+	return req.DoWithContext(ctx, api)
+}
+
+// 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"`
 	Language string `json:"language_code,omitempty"`
 }
 
+// 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) {
 	req := NewRequest[bool]("setMyName", params)
 	return req.Do(api)
 }
 
+// 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) {
+	req := NewRequest[bool]("setMyName", params)
+	return req.DoWithContext(ctx, api)
+}
+
+// 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)
 	return req.Do(api)
 }
 
+// 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) {
+	req := NewRequest[BotName]("getMyName", params)
+	return req.DoWithContext(ctx, api)
+}
+
+// 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"`
 	Language    string `json:"language_code,omitempty"`
 }
 
+// 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) {
 	req := NewRequest[bool]("setMyDescription", params)
 	return req.Do(api)
 }
 
+// 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) {
+	req := NewRequest[bool]("setMyDescription", params)
+	return req.DoWithContext(ctx, api)
+}
+
+// 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)
 	return req.Do(api)
 }
 
+// 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) {
+	req := NewRequest[BotDescription]("getMyDescription", params)
+	return req.DoWithContext(ctx, api)
+}
+
+// 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"`
 	Language         string `json:"language_code,omitempty"`
 }
 
+// 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) {
 	req := NewRequest[bool]("setMyShortDescription", params)
 	return req.Do(api)
 }
 
+// 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) {
+	req := NewRequest[bool]("setMyShortDescription", params)
+	return req.DoWithContext(ctx, api)
+}
+
+// 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)
 	return req.Do(api)
 }
 
-type SetMyProfilePhotoP struct {
+// 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) {
+	req := NewRequest[BotShortDescription]("getMyShortDescription", params)
+	return req.DoWithContext(ctx, api)
+}
+
+// SetMyProfilePhoto holds parameters for the setMyProfilePhoto method.
+// Since: Bot API 9.0
+// See https://core.telegram.org/bots/api#setmyprofilephoto
+type SetMyProfilePhoto struct {
 	Photo InputProfilePhoto `json:"photo"`
 }
 
-func (api *API) SetMyProfilePhoto(params SetMyProfilePhotoP) (bool, error) {
+// 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 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 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) {
 	req := NewRequest[bool]("removeMyProfilePhoto", NoParams)
 	return req.Do(api)
 }
 
-type SetChatMenuButtonP struct {
-	ChatID     int            `json:"chat_id"`
-	MenuButton MenuButtonType `json:"menu_button"`
+// 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) {
+	req := NewRequest[bool]("removeMyProfilePhoto", NoParams)
+	return req.DoWithContext(ctx, api)
 }
 
-func (api *API) SetChatMenuButton(params SetChatMenuButtonP) (bool, error) {
+// SetChatMenuButton holds parameters for the setChatMenuButton method.
+// Since: Bot API 6.0
+// See https://core.telegram.org/bots/api#setchatmenubutton
+type SetChatMenuButton struct {
+	ChatID     int64       `json:"chat_id,omitempty"`
+	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 SetChatMenuButton) (bool, error) {
 	req := NewRequest[bool]("setChatMenuButton", params)
 	return req.Do(api)
 }
 
-type GetChatMenuButtonP struct {
-	ChatID int `json:"chat_id"`
+// 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 SetChatMenuButton) (bool, error) {
+	req := NewRequest[bool]("setChatMenuButton", params)
+	return req.DoWithContext(ctx, api)
 }
 
-func (api *API) GetChatMenuButton(params GetChatMenuButtonP) (BaseMenuButton, error) {
-	req := NewRequest[BaseMenuButton]("getChatMenuButton", params)
+// GetChatMenuButton holds parameters for the getChatMenuButton method.
+// Since: Bot API 6.0
+// See https://core.telegram.org/bots/api#getchatmenubutton
+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 GetChatMenuButton) (MenuButton, error) {
+	req := NewRequest[MenuButton]("getChatMenuButton", params)
 	return req.Do(api)
 }
 
-type SetMyDefaultAdministratorRightsP struct {
+// 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 GetChatMenuButton) (MenuButton, error) {
+	req := NewRequest[MenuButton]("getChatMenuButton", params)
+	return req.DoWithContext(ctx, api)
+}
+
+// SetMyDefaultAdministratorRights holds parameters for the setMyDefaultAdministratorRights method.
+// Since: Bot API 6.0
+// See https://core.telegram.org/bots/api#setmydefaultadministratorrights
+type SetMyDefaultAdministratorRights struct {
 	Rights      *ChatAdministratorRights `json:"rights"`
 	ForChannels bool                     `json:"for_channels"`
 }
 
-func (api *API) SetMyDefaultAdministratorRights(params SetMyDefaultAdministratorRightsP) (bool, error) {
+// 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 SetMyDefaultAdministratorRights) (bool, error) {
 	req := NewRequest[bool]("setMyDefaultAdministratorRights", params)
 	return req.Do(api)
 }
 
-type GetMyDefaultAdministratorRightsP struct {
+// 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 SetMyDefaultAdministratorRights) (bool, error) {
+	req := NewRequest[bool]("setMyDefaultAdministratorRights", params)
+	return req.DoWithContext(ctx, api)
+}
+
+// GetMyDefaultAdministratorRights holds parameters for the getMyDefaultAdministratorRights method.
+// Since: Bot API 6.0
+// See https://core.telegram.org/bots/api#getmydefaultadministratorrights
+type GetMyDefaultAdministratorRights struct {
 	ForChannels bool `json:"for_channels"`
 }
 
-func (api *API) GetMyDefaultAdministratorRights(params GetMyDefaultAdministratorRightsP) (ChatAdministratorRights, error) {
+// 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 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 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)
 	return req.Do(api)
 }
 
-type SendGiftP struct {
-	UserID        int             `json:"user_id,omitempty"`
-	ChatID        int             `json:"chat_id,omitempty"`
+// 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) {
+	req := NewRequest[Gifts]("getAvailableGifts", NoParams)
+	return req.DoWithContext(ctx, api)
+}
+
+// SendGift holds parameters for the sendGift method.
+// Since: Bot API 9.0
+// See https://core.telegram.org/bots/api#sendgift
+type SendGift struct {
+	UserID        int64           `json:"user_id,omitempty"`
+	ChatID        int64           `json:"chat_id,omitempty"`
 	GiftID        string          `json:"gift_id"`
 	PayForUpgrade bool            `json:"pay_for_upgrade"`
 	Text          string          `json:"text"`
@@ -154,13 +403,29 @@ type SendGiftP struct {
 	TextEntities  []MessageEntity `json:"text_entities,omitempty"`
 }
 
-func (api *API) SendGift(params SendGiftP) (bool, error) {
+// 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 SendGift) (bool, error) {
 	req := NewRequest[bool]("sendGift", params)
 	return req.Do(api)
 }
 
-type GiftPremiumSubscriptionP struct {
-	UserID        int             `json:"user_id"`
+// 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 SendGift) (bool, error) {
+	req := NewRequest[bool]("sendGift", params)
+	return req.DoWithContext(ctx, api)
+}
+
+// GiftPremiumSubscription holds parameters for the giftPremiumSubscription method.
+// Since: Bot API 9.0
+// See https://core.telegram.org/bots/api#giftpremiumsubscription
+type GiftPremiumSubscription struct {
+	UserID        int64           `json:"user_id"`
 	MonthCount    int             `json:"month_count"`
 	StarCount     int             `json:"star_count"`
 	Text          string          `json:"text,omitempty"`
@@ -168,7 +433,70 @@ type GiftPremiumSubscriptionP struct {
 	TextEntities  []MessageEntity `json:"text_entities,omitempty"`
 }
 
-func (api *API) GiftPremiumSubscription(params GiftPremiumSubscriptionP) (bool, error) {
+// 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 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 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,64 +1,112 @@
 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"`
 	Description string `json:"description"`
+	// IsEphemeral marks the command as visible only in ephemeral command contexts.
+	IsEphemeral bool `json:"is_ephemeral,omitempty"` // Since: Bot API 10.2
 }
+
+// BotCommandScopeType indicates the type of a command scope.
 type BotCommandScopeType string
 
 const (
-	BotCommandScopeDefaultType               BotCommandScopeType = "default"
-	BotCommandScopePrivateType               BotCommandScopeType = "all_private_chats"
-	BotCommandScopeGroupType                 BotCommandScopeType = "all_group_chats"
+	// BotCommandScopeDefaultType is the default command scope.
+	BotCommandScopeDefaultType BotCommandScopeType = "default"
+	// BotCommandScopePrivateType covers all private chats.
+	BotCommandScopePrivateType BotCommandScopeType = "all_private_chats"
+	// BotCommandScopeGroupType covers all group and supergroup chats.
+	BotCommandScopeGroupType BotCommandScopeType = "all_group_chats"
+	// BotCommandScopeAllChatAdministratorsType covers all chat administrators.
 	BotCommandScopeAllChatAdministratorsType BotCommandScopeType = "all_chat_administrators"
-	BotCommandScopeChatType                  BotCommandScopeType = "chat"
-	BotCommandScopeChatAdministratorsType    BotCommandScopeType = "chat_administrators"
-	BotCommandScopeChatMemberType            BotCommandScopeType = "chat_member"
+	// BotCommandScopeChatType covers a specific chat.
+	BotCommandScopeChatType BotCommandScopeType = "chat"
+	// BotCommandScopeChatAdministratorsType covers administrators of a specific chat.
+	BotCommandScopeChatAdministratorsType BotCommandScopeType = "chat_administrators"
+	// BotCommandScopeChatMemberType covers a specific member of a specific chat.
+	BotCommandScopeChatMemberType BotCommandScopeType = "chat_member"
 )
 
+// 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"`
-	ChatID *int                `json:"chat_id,omitempty"`
-	UserID *int                `json:"user_id,omitempty"`
+	ChatID *int64              `json:"chat_id,omitempty"`
+	UserID *int64              `json:"user_id,omitempty"`
 }
 
+// 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"`
 }
 
+// InputProfilePhotoType indicates the type of a profile photo input.
+type InputProfilePhotoType string
+
 const (
-	InputProfilePhotoStaticType   InputProfilePhotoType = "static"
+	// InputProfilePhotoStaticType identifies a static profile photo input.
+	InputProfilePhotoStaticType InputProfilePhotoType = "static"
+	// InputProfilePhotoAnimatedType identifies an animated profile photo input.
 	InputProfilePhotoAnimatedType InputProfilePhotoType = "animated"
 )
 
-type InputProfilePhotoType string
+// 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"`
 
-	// Static
+	// Static fields (for static photos)
 	Photo *string `json:"photo,omitempty"`
 
-	// Animated
+	// Animated fields (for animated profile videos)
 	Animation          *string  `json:"animation,omitempty"`
 	MainFrameTimestamp *float64 `json:"main_frame_timestamp,omitempty"`
 }
 
+// MenuButtonType indicates the type of a menu button.
+type MenuButtonType string
+
 const (
+	// MenuButtonCommandsType identifies a commands menu button.
 	MenuButtonCommandsType MenuButtonType = "commands"
-	MenuButtonWebAppType   MenuButtonType = "web_app"
-	MenuButtonDefaultType  MenuButtonType = "default"
+	// MenuButtonWebAppType identifies a web app menu button.
+	MenuButtonWebAppType MenuButtonType = "web_app"
+	// MenuButtonDefaultType identifies Telegram's default menu button.
+	MenuButtonDefaultType MenuButtonType = "default"
 )
 
-type MenuButtonType string
-type BaseMenuButton struct {
+// 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"`
-	// WebApp
-	Text   string     `json:"text"`
-	WebApp WebAppInfo `json:"web_app"`
+
+	// WebApp fields (for web_app button)
+	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

@@ -1,147 +1,399 @@
 package tgapi
 
-type VerifyUserP struct {
-	UserID            int    `json:"user_id"`
+import "context"
+
+// VerifyUser holds parameters for the verifyUser method.
+// Since: Bot API 8.0
+// See https://core.telegram.org/bots/api#verifyuser
+type VerifyUser struct {
+	UserID            int64  `json:"user_id"`
 	CustomDescription string `json:"custom_description,omitempty"`
 }
 
-func (api *API) VerifyUser(params VerifyUserP) (bool, error) {
+// 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 VerifyUser) (bool, error) {
 	req := NewRequest[bool]("verifyUser", params)
 	return req.Do(api)
 }
 
-type VerifyChatP struct {
-	ChatID            int    `json:"chat_id"`
+// 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 VerifyUser) (bool, error) {
+	req := NewRequest[bool]("verifyUser", params)
+	return req.DoWithContext(ctx, api)
+}
+
+// VerifyChat holds parameters for the verifyChat method.
+// Since: Bot API 8.0
+// See https://core.telegram.org/bots/api#verifychat
+type VerifyChat struct {
+	ChatID            int64  `json:"chat_id"`
 	CustomDescription string `json:"custom_description,omitempty"`
 }
 
-func (api *API) VerifyChat(params VerifyChatP) (bool, error) {
+// 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 VerifyChat) (bool, error) {
 	req := NewRequest[bool]("verifyChat", params)
 	return req.Do(api)
 }
 
-type RemoveUserVerificationP struct {
-	UserID int `json:"user_id"`
+// 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 VerifyChat) (bool, error) {
+	req := NewRequest[bool]("verifyChat", params)
+	return req.DoWithContext(ctx, api)
 }
 
-func (api *API) RemoveUserVerification(params RemoveUserVerificationP) (bool, error) {
+// RemoveUserVerification holds parameters for the removeUserVerification method.
+// Since: Bot API 8.0
+// See https://core.telegram.org/bots/api#removeuserverification
+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 RemoveUserVerification) (bool, error) {
 	req := NewRequest[bool]("removeUserVerification", params)
 	return req.Do(api)
 }
 
-type RemoveChatVerificationP struct {
-	ChatID int `json:"chat_id"`
+// 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 RemoveUserVerification) (bool, error) {
+	req := NewRequest[bool]("removeUserVerification", params)
+	return req.DoWithContext(ctx, api)
 }
 
-func (api *API) RemoveChatVerification(params RemoveChatVerificationP) (bool, error) {
+// RemoveChatVerification holds parameters for the removeChatVerification method.
+// Since: Bot API 8.0
+// See https://core.telegram.org/bots/api#removechatverification
+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 RemoveChatVerification) (bool, error) {
 	req := NewRequest[bool]("removeChatVerification", params)
 	return req.Do(api)
 }
 
-type ReadBusinessMessageP struct {
+// 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 RemoveChatVerification) (bool, error) {
+	req := NewRequest[bool]("removeChatVerification", params)
+	return req.DoWithContext(ctx, api)
+}
+
+// ReadBusinessMessage holds parameters for the readBusinessMessage method.
+// Since: Bot API 9.0
+// See https://core.telegram.org/bots/api#readbusinessmessage
+type ReadBusinessMessage struct {
 	BusinessConnectionID string `json:"business_connection_id"`
-	ChatID               int    `json:"chat_id"`
+	ChatID               int64  `json:"chat_id"`
 	MessageID            int    `json:"message_id"`
 }
 
-func (api *API) ReadBusinessMessage(params ReadBusinessMessageP) (bool, error) {
+// 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 ReadBusinessMessage) (bool, error) {
 	req := NewRequest[bool]("readBusinessMessage", params)
 	return req.Do(api)
 }
 
-type DeleteBusinessMessageP struct {
+// 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 ReadBusinessMessage) (bool, error) {
+	req := NewRequest[bool]("readBusinessMessage", params)
+	return req.DoWithContext(ctx, api)
+}
+
+// GetBusinessConnection holds parameters for the getBusinessConnection method.
+// Since: Bot API 7.2
+// See https://core.telegram.org/bots/api#getbusinessconnection
+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 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 GetBusinessConnection) (BusinessConnection, error) {
+	req := NewRequest[BusinessConnection]("getBusinessConnection", params)
+	return req.DoWithContext(ctx, api)
+}
+
+// DeleteBusinessMessages holds parameters for the deleteBusinessMessages method.
+// Since: Bot API 9.0
+// See https://core.telegram.org/bots/api#deletebusinessmessages
+type DeleteBusinessMessages struct {
 	BusinessConnectionID string `json:"business_connection_id"`
 	MessageIDs           []int  `json:"message_ids"`
 }
 
-func (api *API) DeleteBusinessMessage(params DeleteBusinessMessageP) (bool, error) {
-	req := NewRequest[bool]("deleteBusinessMessage", params)
+// 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 DeleteBusinessMessages) (bool, error) {
+	req := NewRequest[bool]("deleteBusinessMessages", params)
 	return req.Do(api)
 }
 
-type SetBusinessAccountNameP struct {
+// 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 DeleteBusinessMessages) (bool, error) {
+	req := NewRequest[bool]("deleteBusinessMessages", params)
+	return req.DoWithContext(ctx, api)
+}
+
+// SetBusinessAccountName holds parameters for the setBusinessAccountName method.
+// Since: Bot API 9.0
+// See https://core.telegram.org/bots/api#setbusinessaccountname
+type SetBusinessAccountName struct {
 	BusinessConnectionID string `json:"business_connection_id"`
 	FirstName            string `json:"first_name"`
 	LastName             string `json:"last_name,omitempty"`
 }
 
-func (api *API) SetBusinessAccountName(params SetBusinessAccountNameP) (bool, error) {
+// 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 SetBusinessAccountName) (bool, error) {
 	req := NewRequest[bool]("setBusinessAccountName", params)
 	return req.Do(api)
 }
 
-type SetBusinessAccountUsernameP struct {
+// 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 SetBusinessAccountName) (bool, error) {
+	req := NewRequest[bool]("setBusinessAccountName", params)
+	return req.DoWithContext(ctx, api)
+}
+
+// SetBusinessAccountUsername holds parameters for the setBusinessAccountUsername method.
+// Since: Bot API 9.0
+// See https://core.telegram.org/bots/api#setbusinessaccountusername
+type SetBusinessAccountUsername struct {
 	BusinessConnectionID string `json:"business_connection_id"`
 	Username             string `json:"username,omitempty"`
 }
 
-func (api *API) SetBusinessAccountUsername(params SetBusinessAccountUsernameP) (bool, error) {
+// 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 SetBusinessAccountUsername) (bool, error) {
 	req := NewRequest[bool]("setBusinessAccountUsername", params)
 	return req.Do(api)
 }
 
-type SetBusinessAccountBioP struct {
+// 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 SetBusinessAccountUsername) (bool, error) {
+	req := NewRequest[bool]("setBusinessAccountUsername", params)
+	return req.DoWithContext(ctx, api)
+}
+
+// SetBusinessAccountBio holds parameters for the setBusinessAccountBio method.
+// Since: Bot API 9.0
+// See https://core.telegram.org/bots/api#setbusinessaccountbio
+type SetBusinessAccountBio struct {
 	BusinessConnectionID string `json:"business_connection_id"`
 	Bio                  string `json:"bio,omitempty"`
 }
 
-func (api *API) SetBusinessAccountBio(params SetBusinessAccountBioP) (bool, error) {
+// 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 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 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"`
 	Photo                InputProfilePhoto `json:"photo,omitempty"`
 	IsPublic             bool              `json:"is_public,omitempty"`
 }
 
+// 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) {
 	req := NewRequest[bool]("setBusinessAccountProfilePhoto", params)
 	return req.Do(api)
 }
 
-type RemoveBusinessAccountProfilePhotoP struct {
+// 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) {
+	req := NewRequest[bool]("setBusinessAccountProfilePhoto", params)
+	return req.DoWithContext(ctx, api)
+}
+
+// RemoveBusinessAccountProfilePhoto holds parameters for the removeBusinessAccountProfilePhoto method.
+// Since: Bot API 9.0
+// See https://core.telegram.org/bots/api#removebusinessaccountprofilephoto
+type RemoveBusinessAccountProfilePhoto struct {
 	BusinessConnectionID string `json:"business_connection_id"`
 	IsPublic             bool   `json:"is_public,omitempty"`
 }
 
-func (api *API) RemoveBusinessAccountProfilePhoto(params RemoveBusinessAccountProfilePhotoP) (bool, error) {
+// 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 RemoveBusinessAccountProfilePhoto) (bool, error) {
 	req := NewRequest[bool]("removeBusinessAccountProfilePhoto", params)
 	return req.Do(api)
 }
 
-type SetBusinessAccountGiftSettingsP struct {
+// 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 RemoveBusinessAccountProfilePhoto) (bool, error) {
+	req := NewRequest[bool]("removeBusinessAccountProfilePhoto", params)
+	return req.DoWithContext(ctx, api)
+}
+
+// SetBusinessAccountGiftSettings holds parameters for the setBusinessAccountGiftSettings method.
+// Since: Bot API 9.0
+// See https://core.telegram.org/bots/api#setbusinessaccountgiftsettings
+type SetBusinessAccountGiftSettings struct {
 	BusinessConnectionID string            `json:"business_connection_id"`
 	ShowGiftButton       bool              `json:"show_gift_button"`
 	AcceptedGiftTypes    AcceptedGiftTypes `json:"accepted_gift_types"`
 }
 
-func (api *API) SetBusinessAccountGiftSettings(params SetBusinessAccountGiftSettingsP) (bool, error) {
+// 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 SetBusinessAccountGiftSettings) (bool, error) {
 	req := NewRequest[bool]("setBusinessAccountGiftSettings", params)
 	return req.Do(api)
 }
 
-type GetBusinessAccountStarBalanceP struct {
+// 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 SetBusinessAccountGiftSettings) (bool, error) {
+	req := NewRequest[bool]("setBusinessAccountGiftSettings", params)
+	return req.DoWithContext(ctx, api)
+}
+
+// GetBusinessAccountStarBalance holds parameters for the getBusinessAccountStarBalance method.
+// Since: Bot API 9.0
+// See https://core.telegram.org/bots/api#getbusinessaccountstarbalance
+type GetBusinessAccountStarBalance struct {
 	BusinessConnectionID string `json:"business_connection_id"`
 }
 
-func (api *API) GetBusinessAccountStarBalance(params GetBusinessAccountStarBalanceP) (StarAmount, error) {
-	req := NewRequest[StarAmount]("getBusinessAccountGiftSettings", params)
+// 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 GetBusinessAccountStarBalance) (StarAmount, error) {
+	req := NewRequest[StarAmount]("getBusinessAccountStarBalance", params)
 	return req.Do(api)
 }
 
-type TransferBusinessAccountStartP struct {
+// 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 GetBusinessAccountStarBalance) (StarAmount, error) {
+	req := NewRequest[StarAmount]("getBusinessAccountStarBalance", params)
+	return req.DoWithContext(ctx, api)
+}
+
+// TransferBusinessAccountStars holds parameters for the transferBusinessAccountStars method.
+// Since: Bot API 9.0
+// See https://core.telegram.org/bots/api#transferbusinessaccountstars
+type TransferBusinessAccountStars struct {
 	BusinessConnectionID string `json:"business_connection_id"`
 	StarCount            int    `json:"star_count"`
 }
 
-func (api *API) TransferBusinessAccountStart(params TransferBusinessAccountStartP) (bool, error) {
-	req := NewRequest[bool]("transferBusinessAccountStart", params)
+// 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 TransferBusinessAccountStars) (bool, error) {
+	req := NewRequest[bool]("transferBusinessAccountStars", params)
 	return req.Do(api)
 }
 
-type GetBusinessAccountGiftsP struct {
+// 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 TransferBusinessAccountStars) (bool, error) {
+	req := NewRequest[bool]("transferBusinessAccountStars", params)
+	return req.DoWithContext(ctx, api)
+}
+
+// GetBusinessAccountGifts holds parameters for the getBusinessAccountGifts method.
+// Since: Bot API 9.0
+// See https://core.telegram.org/bots/api#getbusinessaccountgifts
+type GetBusinessAccountGifts struct {
 	BusinessConnectionID        string `json:"business_connection_id"`
 	ExcludeUnsaved              bool   `json:"exclude_unsaved,omitempty"`
 	ExcludeSaved                bool   `json:"exclude_saved,omitempty"`
@@ -155,46 +407,109 @@ type GetBusinessAccountGiftsP struct {
 	Limit                       int    `json:"limit,omitempty"`
 }
 
-func (api *API) GetBusinessAccountGifts(params GetBusinessAccountGiftsP) (OwnedGifts, error) {
+// 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 GetBusinessAccountGifts) (OwnedGifts, error) {
 	req := NewRequest[OwnedGifts]("getBusinessAccountGifts", params)
 	return req.Do(api)
 }
 
-type ConvertGiftToStarsP struct {
+// 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 GetBusinessAccountGifts) (OwnedGifts, error) {
+	req := NewRequest[OwnedGifts]("getBusinessAccountGifts", params)
+	return req.DoWithContext(ctx, api)
+}
+
+// ConvertGiftToStars holds parameters for the convertGiftToStars method.
+// Since: Bot API 9.0
+// See https://core.telegram.org/bots/api#convertgifttostars
+type ConvertGiftToStars struct {
 	BusinessConnectionID string `json:"business_connection_id"`
 	OwnedGiftID          string `json:"owned_gift_id"`
 }
 
-func (api *API) ConvertGiftToStars(params ConvertGiftToStarsP) (bool, error) {
+// 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 ConvertGiftToStars) (bool, error) {
 	req := NewRequest[bool]("convertGiftToStars", params)
 	return req.Do(api)
 }
 
-type UpgradeGiftP struct {
+// 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 ConvertGiftToStars) (bool, error) {
+	req := NewRequest[bool]("convertGiftToStars", params)
+	return req.DoWithContext(ctx, api)
+}
+
+// UpgradeGift holds parameters for the upgradeGift method.
+// Since: Bot API 9.0
+// See https://core.telegram.org/bots/api#upgradegift
+type UpgradeGift struct {
 	BusinessConnectionID string `json:"business_connection_id"`
 	OwnedGiftID          string `json:"owned_gift_id"`
 	KeepOriginalDetails  bool   `json:"keep_original_details,omitempty"`
 	StarCount            int    `json:"star_count,omitempty"`
 }
 
-func (api *API) UpgradeGift(params UpgradeGiftP) (bool, error) {
+// 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 UpgradeGift) (bool, error) {
 	req := NewRequest[bool]("upgradeGift", params)
 	return req.Do(api)
 }
 
-type TransferGiftP struct {
+// 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 UpgradeGift) (bool, error) {
+	req := NewRequest[bool]("upgradeGift", params)
+	return req.DoWithContext(ctx, api)
+}
+
+// TransferGift holds parameters for the transferGift method.
+// Since: Bot API 9.0
+// See https://core.telegram.org/bots/api#transfergift
+type TransferGift struct {
 	BusinessConnectionID string `json:"business_connection_id"`
 	OwnedGiftID          string `json:"owned_gift_id"`
-	NewOwnerChatID       int    `json:"new_owner_chat_id"`
+	NewOwnerChatID       int64  `json:"new_owner_chat_id"`
 	StarCount            int    `json:"star_count,omitempty"`
 }
 
-func (api *API) TransferGift(params TransferGiftP) (bool, error) {
+// 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 TransferGift) (bool, error) {
 	req := NewRequest[bool]("transferGift", params)
 	return req.Do(api)
 }
 
-type PostStoryP struct {
+// 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 TransferGift) (bool, error) {
+	req := NewRequest[bool]("transferGift", params)
+	return req.DoWithContext(ctx, api)
+}
+
+// PostStory holds parameters for the postStory method.
+// Since: Bot API 7.2
+// See https://core.telegram.org/bots/api#poststory
+type PostStory struct {
 	BusinessConnectionID string            `json:"business_connection_id"`
 	Content              InputStoryContent `json:"content"`
 	ActivePeriod         int               `json:"active_period"`
@@ -208,30 +523,57 @@ type PostStoryP struct {
 	ProtectContent bool `json:"protect_content,omitempty"`
 }
 
-func (api *API) PostStoryPhoto(params PostStoryP) (Story, error) {
-	req := NewRequest[Story]("postStory", params)
-	return req.Do(api)
-}
-func (api *API) PostStoryVideo(params PostStoryP) (Story, error) {
+// PostStory posts a story with a photo.
+// Since: Bot API 7.2
+// See https://core.telegram.org/bots/api#poststory
+func (api *API) PostStory(params PostStory) (Story, error) {
 	req := NewRequest[Story]("postStory", params)
 	return req.Do(api)
 }
 
-type RepostStoryP struct {
+// 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) PostStoryWithContext(ctx context.Context, params PostStory) (Story, error) {
+	req := NewRequest[Story]("postStory", params)
+	return req.DoWithContext(ctx, api)
+}
+
+// RepostStory holds parameters for the repostStory method.
+// Since: Bot API 7.2
+// See https://core.telegram.org/bots/api#repoststory
+type RepostStory struct {
 	BusinessConnectionID string `json:"business_connection_id"`
-	FromChatID           int    `json:"from_chat_id"`
+	FromChatID           int64  `json:"from_chat_id"`
 	FromStoryID          int    `json:"from_story_id"`
 	ActivePeriod         int    `json:"active_period"`
 	PostToChatPage       bool   `json:"post_to_chat_page,omitempty"`
 	ProtectContent       bool   `json:"protect_content,omitempty"`
 }
 
-func (api *API) RepostStory(params RepostStoryP) (Story, error) {
+// 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 RepostStory) (Story, error) {
 	req := NewRequest[Story]("repostStory", params)
 	return req.Do(api)
 }
 
-type EditStoryP struct {
+// 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 RepostStory) (Story, error) {
+	req := NewRequest[Story]("repostStory", params)
+	return req.DoWithContext(ctx, api)
+}
+
+// EditStory holds parameters for the editStory method.
+// Since: Bot API 7.2
+// See https://core.telegram.org/bots/api#editstory
+type EditStory struct {
 	BusinessConnectionID string            `json:"business_connection_id"`
 	StoryID              int               `json:"story_id"`
 	Content              InputStoryContent `json:"content"`
@@ -242,17 +584,46 @@ type EditStoryP struct {
 	Areas           []StoryArea     `json:"areas,omitempty"`
 }
 
-func (api *API) EditStory(params EditStoryP) (Story, error) {
+// 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 EditStory) (Story, error) {
 	req := NewRequest[Story]("editStory", params)
 	return req.Do(api)
 }
 
-type DeleteStoryP struct {
+// 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 EditStory) (Story, error) {
+	req := NewRequest[Story]("editStory", params)
+	return req.DoWithContext(ctx, api)
+}
+
+// DeleteStory holds parameters for the deleteStory method.
+// Since: Bot API 7.2
+// See https://core.telegram.org/bots/api#deletestory
+type DeleteStory struct {
 	BusinessConnectionID string `json:"business_connection_id"`
 	StoryID              int    `json:"story_id"`
 }
 
-func (api *API) DeleteStory(params DeleteStoryP) (bool, error) {
+// 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 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 DeleteStory) (bool, error) {
+	req := NewRequest[bool]("deleteStory", params)
+	return req.DoWithContext(ctx, api)
+}

tgapi/business_types.go

@@ -1,23 +1,42 @@
 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"`
 	Message string   `json:"message,omitempty"`
 	Sticker *Sticker `json:"sticker,omitempty"`
 }
+
+// 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"`
 	Location *Location `json:"location,omitempty"`
 }
+
+// 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"`
 	ClosingMinute int `json:"closing_minute"`
 }
+
+// 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"`
-	OpeningHours []Birthdate `json:"opening_hours"`
+	TimeZoneName string                         `json:"time_zone_name"`
+	OpeningHours []BusinessOpeningHoursInterval `json:"opening_hours"`
 }
 
+// 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"`
 	CanReadMessages            *bool `json:"can_read_messages,omitempty"`
@@ -34,33 +53,57 @@ type BusinessBotRights struct {
 	CanTransferStars           *bool `json:"can_transfer_stars,omitempty"`
 	CanManageStories           *bool `json:"can_manage_stories,omitempty"`
 }
+
+// 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"`
 	User       User               `json:"user"`
-	UserChatID int                `json:"user_chat_id"`
+	UserChatID int64              `json:"user_chat_id"`
 	Date       int                `json:"date"`
 	Rights     *BusinessBotRights `json:"rights,omitempty"`
-	IsEnabled  bool               `json:"id_enabled"`
+	IsEnabled  bool               `json:"is_enabled"`
 }
 
+// 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"`
+	Chat                 Chat   `json:"chat"`
+	MessageIDs           []int  `json:"message_ids"`
+}
+
+// InputStoryContentType indicates the type of input story content.
+type InputStoryContentType string
+
 const (
+	// InputStoryContentPhotoType identifies photo story content.
 	InputStoryContentPhotoType InputStoryContentType = "photo"
+	// InputStoryContentVideoType identifies video story content.
 	InputStoryContentVideoType InputStoryContentType = "video"
 )
 
-type InputStoryContentType string
+// 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"`
-	// Photo
+
+	// Photo fields
 	Photo *string `json:"photo,omitempty"`
 
-	// Video
+	// Video fields
 	Video               *string  `json:"video,omitempty"`
 	Duration            *float64 `json:"duration,omitempty"`
 	CoverFrameTimestamp *float64 `json:"cover_frame_timestamp,omitempty"`
 	IsAnimation         *bool    `json:"is_animation,omitempty"`
 }
 
+// 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"`
 	YPercentage            float64 `json:"y_percentage"`
@@ -70,34 +113,53 @@ type StoryAreaPosition struct {
 	CornerRadiusPercentage float64 `json:"corner_radius_percentage"`
 }
 
+// StoryAreaTypeType indicates the type of story area.
+type StoryAreaTypeType string
+
 const (
-	StoryAreaTypeLocationType   StoryAreaTypeType = "location"
-	StoryAreaTypeReactionType   StoryAreaTypeType = "suggested_reaction"
-	StoryAreaTypeLinkType       StoryAreaTypeType = "link"
-	StoryAreaTypeWeatherType    StoryAreaTypeType = "weather"
+	// StoryAreaTypeLocationType identifies a location story area.
+	StoryAreaTypeLocationType StoryAreaTypeType = "location"
+	// StoryAreaTypeReactionType identifies a suggested reaction story area.
+	StoryAreaTypeReactionType StoryAreaTypeType = "suggested_reaction"
+	// StoryAreaTypeLinkType identifies a link story area.
+	StoryAreaTypeLinkType StoryAreaTypeType = "link"
+	// StoryAreaTypeWeatherType identifies a weather story area.
+	StoryAreaTypeWeatherType StoryAreaTypeType = "weather"
+	// StoryAreaTypeUniqueGiftType identifies a unique gift story area.
 	StoryAreaTypeUniqueGiftType StoryAreaTypeType = "unique_gift"
 )
 
-type StoryAreaTypeType string
+// StoryAreaType describes the type of a clickable area on a story.
+// Since: Bot API 9.0
+// See https://core.telegram.org/bots/api#storyareatype
 type StoryAreaType struct {
 	Type StoryAreaTypeType `json:"type"`
 
+	// Location
 	Latitude  *float64         `json:"latitude,omitempty"`
 	Longitude *float64         `json:"longitude,omitempty"`
 	Address   *LocationAddress `json:"address,omitempty"`
 
+	// Suggested reaction
 	ReactionType *ReactionType `json:"reaction_type,omitempty"`
 	IsDark       *bool         `json:"is_dark,omitempty"`
 	IsFlipped    *bool         `json:"is_flipped,omitempty"`
 
+	// Link
 	URL *string `json:"url,omitempty"`
 
+	// Weather
 	Temperature     *float64 `json:"temperature,omitempty"`
-	Emoji           *string  `json:"emoji"`
-	BackgroundColor *int     `json:"background_color"`
+	Emoji           *string  `json:"emoji,omitempty"`
+	BackgroundColor *int     `json:"background_color,omitempty"`
 
+	// Unique gift
 	Name *string `json:"name,omitempty"`
 }
+
+// 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"`
 	Type     StoryAreaType     `json:"type"`

tgapi/chat_types.go

@@ -1,27 +1,38 @@
 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               int     `json:"id"`
-	Type             string  `json:"type"`
-	Title            *string `json:"title,omitempty"`
-	Username         *string `json:"username,omitempty"`
-	FirstName        *string `json:"first_name,omitempty"`
-	LastName         *string `json:"last_name,omitempty"`
-	IsForum          *bool   `json:"is_forum,omitempty"`
-	IsDirectMessages *bool   `json:"is_direct_messages,omitempty"`
+	ID               int64    `json:"id"`
+	Type             ChatType `json:"type"`
+	Title            *string  `json:"title,omitempty"`
+	Username         *string  `json:"username,omitempty"`
+	FirstName        *string  `json:"first_name,omitempty"`
+	LastName         *string  `json:"last_name,omitempty"`
+	IsForum          *bool    `json:"is_forum,omitempty"`           // Since: Bot API 6.3
+	IsDirectMessages *bool    `json:"is_direct_messages,omitempty"` // Since: Bot API 9.2
 }
 
+// ChatType represents the type of a chat.
 type ChatType string
 
 const (
-	ChatTypePrivate    ChatType = "private"
-	ChatTypeGroup      ChatType = "group"
+	// ChatTypePrivate identifies a private chat.
+	ChatTypePrivate ChatType = "private"
+	// ChatTypeGroup identifies a basic group chat.
+	ChatTypeGroup ChatType = "group"
+	// ChatTypeSupergroup identifies a supergroup chat.
 	ChatTypeSupergroup ChatType = "supergroup"
-	ChatTypeChannel    ChatType = "channel"
+	// ChatTypeChannel identifies a channel chat.
+	ChatTypeChannel ChatType = "channel"
 )
 
+// ChatFullInfo contains full information about a chat.
+// Since: Bot API 7.5
+// See https://core.telegram.org/bots/api#chatfullinfo
 type ChatFullInfo struct {
-	ID               int        `json:"id"`
+	ID               int64      `json:"id"`
 	Type             ChatType   `json:"type"`
 	Title            string     `json:"title"`
 	Username         string     `json:"username"`
@@ -40,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"`
 
@@ -73,15 +84,22 @@ type ChatFullInfo struct {
 	StickerSetName               *string `json:"sticker_set_name,omitempty"`
 	CanSetStickerSet             *bool   `json:"can_set_sticker_set,omitempty"`
 	CustomEmojiStickerSetName    *string `json:"custom_emoji_sticker_set_name,omitempty"`
-	LinkedChatID                 *int    `json:"linked_chat_id,omitempty"`
+	LinkedChatID                 *int64  `json:"linked_chat_id,omitempty"`
 
 	Location             *ChatLocation     `json:"location,omitempty"`
 	Rating               *UserRating       `json:"rating,omitempty"`
-	FirstProfileAudio    *Audio            `json:"first_profile_audio,omitempty"`
-	UniqueGiftColors     *UniqueGiftColors `json:"unique_gift_colors,omitempty"`
-	PaidMessageStarCount *int              `json:"paid_message_star_count,omitempty"`
+	FirstProfileAudio    *Audio            `json:"first_profile_audio,omitempty"`     // Since: Bot API 9.4
+	UniqueGiftColors     *UniqueGiftColors `json:"unique_gift_colors,omitempty"`      // Since: Bot API 9.3
+	PaidMessageStarCount *int              `json:"paid_message_star_count,omitempty"` // Since: Bot API 9.3
+	// GuardBot contains the guard bot visible to chat administrators.
+	GuardBot *User `json:"guard_bot,omitempty"` // Since: Bot API 10.1; visible to chat administrators only
+	// Community contains information about the affected community.
+	Community *Community `json:"community,omitempty"` // Since: Bot API 10.2
 }
 
+// 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"`
 	SmallFileUniqueID string `json:"small_file_unique_id"`
@@ -89,29 +107,43 @@ type ChatPhoto struct {
 	BigFileUniqueID   string `json:"big_file_unique_id"`
 }
 
+// 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"`
-	CanSendDocuments     bool `json:"can_send_documents"`
-	CanSendPhotos        bool `json:"can_send_photos"`
-	CanSendVideoNotes    bool `json:"can_send_video_notes"`
-	CanSendVoiceNotes    bool `json:"can_send_voice_notes"`
+	CanSendAudios        bool `json:"can_send_audios"`      // Since: Bot API 6.5
+	CanSendDocuments     bool `json:"can_send_documents"`   // Since: Bot API 6.5
+	CanSendPhotos        bool `json:"can_send_photos"`      // Since: Bot API 6.5
+	CanSendVideos        bool `json:"can_send_videos"`      // Since: Bot API 6.5
+	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"`
+	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"`
 	Address  string   `json:"address"`
 }
+
+// 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"`
 	Creator           User   `json:"creator"`
-	CreateJoinRequest bool   `json:"create_join_request"`
+	CreateJoinRequest bool   `json:"creates_join_request"`
 	IsPrimary         bool   `json:"is_primary"`
 	IsRevoked         bool   `json:"is_revoked"`
 
@@ -123,20 +155,31 @@ type ChatInviteLink struct {
 	SubscriptionPrice       *int    `json:"subscription_price,omitempty"`
 }
 
+// ChatMemberStatusType indicates the status of a chat member.
 type ChatMemberStatusType string
 
 const (
-	ChatMemberStatusOwner         ChatMemberStatusType = "owner"
+	// ChatMemberStatusOwner identifies a chat owner.
+	ChatMemberStatusOwner ChatMemberStatusType = "owner"
+	// ChatMemberStatusAdministrator identifies a chat administrator.
 	ChatMemberStatusAdministrator ChatMemberStatusType = "administrator"
-	ChatMemberStatusMember        ChatMemberStatusType = "member"
-	ChatMemberStatusRestricted    ChatMemberStatusType = "restricted"
-	ChatMemberStatusLeft          ChatMemberStatusType = "left"
-	ChatMemberStatusBanned        ChatMemberStatusType = "kicked"
+	// ChatMemberStatusMember identifies a regular member.
+	ChatMemberStatusMember ChatMemberStatusType = "member"
+	// ChatMemberStatusRestricted identifies a restricted member.
+	ChatMemberStatusRestricted ChatMemberStatusType = "restricted"
+	// ChatMemberStatusLeft identifies a user who left the chat.
+	ChatMemberStatusLeft ChatMemberStatusType = "left"
+	// ChatMemberStatusBanned identifies a banned user.
+	ChatMemberStatusBanned ChatMemberStatusType = "kicked"
 )
 
+// 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"` // Since: Bot API 9.5
 
 	// Owner
 	IsAnonymous *bool   `json:"is_anonymous"`
@@ -151,15 +194,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"`
-	CanEditStories      *bool `json:"can_edit_stories,omitempty"`
-	CanDeleteStories    *bool `json:"can_delete_stories,omitempty"`
+	CanPostStories      *bool `json:"can_post_stories,omitempty"`   // Since: Bot API 6.9
+	CanEditStories      *bool `json:"can_edit_stories,omitempty"`   // Since: Bot API 6.9
+	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"`
-	CanManageDirectMessages *bool `json:"can_manage_direct_messages,omitempty"`
+	CanManageTopics         *bool `json:"can_manage_topics,omitempty"`          // Since: Bot API 6.3
+	CanManageDirectMessages *bool `json:"can_manage_direct_messages,omitempty"` // Since: Bot API 9.1
+	CanManageTags           *bool `json:"can_manage_tags,omitempty"`            // Since: Bot API 9.5
 
 	// Member
 	UntilDate *int `json:"until_date,omitempty"`
@@ -167,16 +211,22 @@ type ChatMember struct {
 	// Restricted
 	IsMember             *bool `json:"is_member,omitempty"`
 	CanSendMessages      *bool `json:"can_send_messages,omitempty"`
-	CanSendAudios        *bool `json:"can_send_audios,omitempty"`
-	CanSendDocuments     *bool `json:"can_send_documents,omitempty"`
-	CanSendVideos        *bool `json:"can_send_videos,omitempty"`
-	CanSendVideoNotes    *bool `json:"can_send_video_notes,omitempty"`
-	CanSendVoiceNotes    *bool `json:"can_send_voice_notes,omitempty"`
+	CanSendAudios        *bool `json:"can_send_audios,omitempty"`      // Since: Bot API 6.5
+	CanSendDocuments     *bool `json:"can_send_documents,omitempty"`   // Since: Bot API 6.5
+	CanSendPhotos        *bool `json:"can_send_photos,omitempty"`      // Since: Bot API 6.5
+	CanSendVideos        *bool `json:"can_send_videos,omitempty"`      // Since: Bot API 6.5
+	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"`
+	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"`
 	User   User   `json:"user"`
@@ -187,16 +237,52 @@ type ChatBoostSource struct {
 	IsUnclaimed       *bool `json:"is_unclaimed,omitempty"`
 }
 
+// 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        int             `json:"boost_id"`
+	BoostID        string          `json:"boost_id"`
 	AddDate        int             `json:"add_date"`
 	ExpirationDate int             `json:"expiration_date"`
 	Source         ChatBoostSource `json:"source"`
 }
+
+// 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"`
 	CanManageChat       bool `json:"can_manage_chat"`
@@ -215,16 +301,46 @@ type ChatAdministratorRights struct {
 	CanPinMessages          *bool `json:"can_pin_messages,omitempty"`
 	CanManageTopics         *bool `json:"can_manage_topics,omitempty"`
 	CanManageDirectMessages *bool `json:"can_manage_direct_messages,omitempty"`
+	CanManageTags           *bool `json:"can_manage_tags,omitempty"`
 }
 
+// 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"`
 	Boost ChatBoost `json:"boost"`
 }
 
+// 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"`
 	BoostID    string          `json:"boost_id"`
 	RemoveDate int             `json:"remove_date"`
 	Source     ChatBoostSource `json:"source"`
 }
+
+// Community represents a group of chats.
+//
+// Since: Bot API 10.2
+type Community struct {
+	// ID uniquely identifies the value within its containing object.
+	ID int64 `json:"id"`
+	// Name is the user-facing or reference name of the value.
+	Name string `json:"name"`
+}
+
+// CommunityChatAdded describes a service message about a chat joining a community.
+//
+// Since: Bot API 10.2
+type CommunityChatAdded struct {
+	// Community contains information about the affected community.
+	Community Community `json:"community"`
+}
+
+// CommunityChatRemoved describes a service message about a chat leaving a community.
+//
+// Since: Bot API 10.2
+type CommunityChatRemoved struct{}

tgapi/errors.go

@@ -0,0 +1,35 @@
+package tgapi
+
+import (
+	"errors"
+	"fmt"
+)
+
+// ErrPoolUnexpected reports an unexpected result type returned from the worker pool.
+var ErrPoolUnexpected = errors.New("unexpected response from pool")
+
+// ErrPoolQueueFull reports that the internal request queue is full.
+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")
+
+// ErrRichMessageDraftUploadUnsupported reports a direct file upload attempted for a rich draft.
+//
+// Since: Bot API 10.2
+var ErrRichMessageDraftUploadUnsupported = errors.New("sendRichMessageDraft does not support direct file uploads")
+
+// 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

@@ -1,86 +1,276 @@
 package tgapi
 
-type BaseForumTopicP struct {
-	ChatID          int `json:"chat_id"`
-	MessageThreadID int `json:"message_thread_id"`
+import "context"
+
+// BaseForumTopic contains common fields for forum topic operations that require a chat ID and a message thread ID.
+// Since: Bot API 6.3
+type BaseForumTopic struct {
+	ChatID          int64 `json:"chat_id"`
+	MessageThreadID int   `json:"message_thread_id"`
 }
 
-func (api *API) GetForumTopicIconSet() ([]Sticker, error) {
-	req := NewRequest[[]Sticker]("getForumTopicIconSet", NoParams)
+// 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)
 	return req.Do(api)
 }
 
-type CreateForumTopicP struct {
-	ChatID            int                 `json:"chat_id"`
+// 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) {
+	req := NewRequest[[]Sticker]("getForumTopicIconStickers", NoParams)
+	return req.DoWithContext(ctx, api)
+}
+
+// CreateForumTopic holds parameters for the createForumTopic method.
+// Since: Bot API 6.3
+// See https://core.telegram.org/bots/api#createforumtopic
+type CreateForumTopic struct {
+	ChatID            int64               `json:"chat_id"`
 	Name              string              `json:"name"`
 	IconColor         ForumTopicIconColor `json:"icon_color"`
 	IconCustomEmojiID string              `json:"icon_custom_emoji_id"`
 }
 
-func (api *API) CreateForumTopic(params CreateForumTopicP) (ForumTopic, error) {
-	req := NewRequest[ForumTopic]("createForumTopic", params)
+// 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 CreateForumTopic) (ForumTopic, error) {
+	req := NewRequestWithChatID[ForumTopic]("createForumTopic", params, params.ChatID)
 	return req.Do(api)
 }
 
-type EditForumTopicP struct {
-	BaseForumTopicP
+// 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 CreateForumTopic) (ForumTopic, error) {
+	req := NewRequestWithChatID[ForumTopic]("createForumTopic", params, params.ChatID)
+	return req.DoWithContext(ctx, api)
+}
+
+// EditForumTopic holds parameters for the editForumTopic method.
+// Since: Bot API 6.3
+// See https://core.telegram.org/bots/api#editforumtopic
+type EditForumTopic struct {
+	BaseForumTopic
 	Name              string `json:"name"`
 	IconCustomEmojiID string `json:"icon_custom_emoji_id"`
 }
 
-func (api *API) EditForumTopic(params EditForumTopicP) (bool, error) {
-	req := NewRequest[bool]("editForumTopic", params)
+// 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 EditForumTopic) (bool, error) {
+	req := NewRequestWithChatID[bool]("editForumTopic", params, params.ChatID)
 	return req.Do(api)
 }
 
-func (api *API) CloseForumTopic(params BaseForumTopicP) (bool, error) {
-	req := NewRequest[bool]("closeForumTopic", params)
-	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 EditForumTopic) (bool, error) {
+	req := NewRequestWithChatID[bool]("editForumTopic", params, params.ChatID)
+	return req.DoWithContext(ctx, api)
 }
-func (api *API) ReopenForumTopic(params BaseForumTopicP) (bool, error) {
-	req := NewRequest[bool]("reopenForumTopic", params)
-	return req.Do(api)
-}
-func (api *API) DeleteForumTopic(params BaseForumTopicP) (bool, error) {
-	req := NewRequest[bool]("deleteForumTopic", params)
-	return req.Do(api)
-}
-func (api *API) UnpinAllForumTopicMessages(params BaseForumTopicP) (bool, error) {
-	req := NewRequest[bool]("unpinAllForumTopicMessages", params)
+
+// 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 BaseForumTopic) (bool, error) {
+	req := NewRequestWithChatID[bool]("closeForumTopic", params, params.ChatID)
 	return req.Do(api)
 }
 
-type BaseGeneralForumTopicP struct {
-	ChatID int `json:"chat_id"`
+// 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 BaseForumTopic) (bool, error) {
+	req := NewRequestWithChatID[bool]("closeForumTopic", params, params.ChatID)
+	return req.DoWithContext(ctx, api)
 }
 
-type EditGeneralForumTopicP struct {
-	ChatID int    `json:"chat_id"`
+// 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 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 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 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 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 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 BaseForumTopic) (bool, error) {
+	req := NewRequestWithChatID[bool]("unpinAllForumTopicMessages", params, params.ChatID)
+	return req.DoWithContext(ctx, api)
+}
+
+// BaseGeneralForumTopic contains common fields for general forum topic operations that require a chat ID.
+// Since: Bot API 6.4
+type BaseGeneralForumTopic struct {
+	ChatID int64 `json:"chat_id"`
+}
+
+// EditGeneralForumTopic holds parameters for the editGeneralForumTopic method.
+// Since: Bot API 6.4
+// See https://core.telegram.org/bots/api#editgeneralforumtopic
+type EditGeneralForumTopic struct {
+	ChatID int64  `json:"chat_id"`
 	Name   string `json:"name"`
 }
 
-func (api *API) EditGeneralForumTopic(params EditGeneralForumTopicP) (bool, error) {
-	req := NewRequest[bool]("editGeneralForumTopic", params)
+// 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 EditGeneralForumTopic) (bool, error) {
+	req := NewRequestWithChatID[bool]("editGeneralForumTopic", params, params.ChatID)
 	return req.Do(api)
 }
 
-func (api *API) CloseGeneralForumTopic(params BaseGeneralForumTopicP) (bool, error) {
-	req := NewRequest[bool]("closeGeneralForumTopic", params)
+// 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 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 BaseGeneralForumTopic) (bool, error) {
+	req := NewRequestWithChatID[bool]("closeGeneralForumTopic", params, params.ChatID)
 	return req.Do(api)
 }
-func (api *API) ReopenGeneralForumTopic(params BaseGeneralForumTopicP) (bool, error) {
-	req := NewRequest[bool]("reopenGeneralForumTopic", params)
+
+// 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 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 BaseGeneralForumTopic) (bool, error) {
+	req := NewRequestWithChatID[bool]("reopenGeneralForumTopic", params, params.ChatID)
 	return req.Do(api)
 }
-func (api *API) HideGeneralForumTopic(params BaseGeneralForumTopicP) (bool, error) {
-	req := NewRequest[bool]("hideGeneralForumTopic", params)
+
+// 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 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 BaseGeneralForumTopic) (bool, error) {
+	req := NewRequestWithChatID[bool]("hideGeneralForumTopic", params, params.ChatID)
 	return req.Do(api)
 }
-func (api *API) UnhideGeneralForumTopic(params BaseGeneralForumTopicP) (bool, error) {
-	req := NewRequest[bool]("unhideGeneralForumTopic", params)
+
+// 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 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 BaseGeneralForumTopic) (bool, error) {
+	req := NewRequestWithChatID[bool]("unhideGeneralForumTopic", params, params.ChatID)
 	return req.Do(api)
 }
-func (api *API) UnpinAllGeneralForumTopicMessages(params BaseGeneralForumTopicP) (bool, error) {
-	req := NewRequest[bool]("unpinAllGeneralForumTopicMessages", params)
+
+// 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 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 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 BaseGeneralForumTopic) (bool, error) {
+	req := NewRequestWithChatID[bool]("unpinAllGeneralForumTopicMessages", params, params.ChatID)
+	return req.DoWithContext(ctx, api)
+}

tgapi/forum_types.go

@@ -1,5 +1,8 @@
 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"`
 	Name              string `json:"name"`
@@ -8,8 +11,45 @@ type ForumTopic struct {
 	IsNameImplicit    bool   `json:"is_name_implicit,omitempty"`
 }
 
+// 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
 
 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

@@ -0,0 +1,111 @@
+package tgapi
+
+import "context"
+
+// SendGame holds parameters for the sendGame method.
+// Since: Bot API 2.2
+// See https://core.telegram.org/bots/api#sendgame
+type SendGame struct {
+	BusinessConnectionID string `json:"business_connection_id,omitempty"`
+	ChatID               int64  `json:"chat_id"`
+	MessageThreadID      int    `json:"message_thread_id,omitempty"`
+
+	GameShortName string `json:"game_short_name"`
+
+	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"`
+	ReplyParameters     *ReplyParameters      `json:"reply_parameters,omitempty"`
+	ReplyMarkup         *InlineKeyboardMarkup `json:"reply_markup,omitempty"`
+}
+
+// SendGame sends a game message.
+// Since: Bot API 2.2
+// See https://core.telegram.org/bots/api#sendgame
+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 SendGame) (Message, error) {
+	req := NewRequestWithChatID[Message]("sendGame", params, params.ChatID)
+	return req.DoWithContext(ctx, api)
+}
+
+// SetGameScore holds parameters for the setGameScore method.
+// Since: Bot API 2.2
+// See https://core.telegram.org/bots/api#setgamescore
+type SetGameScore struct {
+	UserID             int64  `json:"user_id"`
+	Score              int    `json:"score"`
+	Force              bool   `json:"force,omitempty"`
+	DisableEditMessage bool   `json:"disable_edit_message,omitempty"`
+	ChatID             int64  `json:"chat_id,omitempty"`
+	MessageID          int    `json:"message_id,omitempty"`
+	InlineMessageID    string `json:"inline_message_id,omitempty"`
+}
+
+// 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 SetGameScore) (Message, bool, error) {
+	var zero Message
+	if params.InlineMessageID != "" {
+		req := NewRequestWithChatID[bool]("setGameScore", params, params.ChatID)
+		res, err := req.Do(api)
+		return zero, res, err
+	}
+	req := NewRequestWithChatID[Message]("setGameScore", params, params.ChatID)
+	res, err := req.Do(api)
+	return res, false, err
+}
+
+// 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 SetGameScore) (Message, bool, error) {
+	var zero Message
+	if params.InlineMessageID != "" {
+		req := NewRequestWithChatID[bool]("setGameScore", params, params.ChatID)
+		res, err := req.DoWithContext(ctx, api)
+		return zero, res, err
+	}
+	req := NewRequestWithChatID[Message]("setGameScore", params, params.ChatID)
+	res, err := req.DoWithContext(ctx, api)
+	return res, false, err
+}
+
+// GetGameHighScores holds parameters for the getGameHighScores method.
+// Since: Bot API 2.2
+// See https://core.telegram.org/bots/api#getgamehighscores
+type GetGameHighScores struct {
+	UserID          int64  `json:"user_id"`
+	ChatID          int64  `json:"chat_id,omitempty"`
+	MessageID       int    `json:"message_id,omitempty"`
+	InlineMessageID string `json:"inline_message_id,omitempty"`
+}
+
+// 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 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 GetGameHighScores) ([]GameHighScore, error) {
+	req := NewRequestWithChatID[[]GameHighScore]("getGameHighScores", params, params.ChatID)
+	return req.DoWithContext(ctx, api)
+}

tgapi/games_types.go

@@ -0,0 +1,25 @@
+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"`
+	User     User `json:"user"`
+	Score    int  `json:"score"`
+}

tgapi/inline_methods.go

@@ -0,0 +1,112 @@
+package tgapi
+
+import "context"
+
+// AnswerInlineQuery holds parameters for the answerInlineQuery method.
+// Since: Bot API 1.7
+// See https://core.telegram.org/bots/api#answerinlinequery
+type AnswerInlineQuery struct {
+	InlineQueryID string                    `json:"inline_query_id"`
+	Results       []InlineQueryResult       `json:"results"`
+	CacheTime     int                       `json:"cache_time,omitempty"`
+	IsPersonal    bool                      `json:"is_personal,omitempty"`
+	NextOffset    string                    `json:"next_offset,omitempty"`
+	Button        *InlineQueryResultsButton `json:"button,omitempty"`
+}
+
+// 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 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 AnswerInlineQuery) (bool, error) {
+	req := NewRequest[bool]("answerInlineQuery", params)
+	return req.DoWithContext(ctx, api)
+}
+
+// AnswerWebAppQuery holds parameters for the answerWebAppQuery method.
+// Since: Bot API 8.0
+// See https://core.telegram.org/bots/api#answerwebappquery
+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 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 AnswerWebAppQuery) (SentWebAppMessage, error) {
+	req := NewRequest[SentWebAppMessage]("answerWebAppQuery", params)
+	return req.DoWithContext(ctx, api)
+}
+
+// SavePreparedInlineMessage holds parameters for the savePreparedInlineMessage method.
+// Since: Bot API 8.0
+// See https://core.telegram.org/bots/api#savepreparedinlinemessage
+type SavePreparedInlineMessage struct {
+	UserID            int64             `json:"user_id"`
+	Result            InlineQueryResult `json:"result"`
+	AllowUserChats    bool              `json:"allow_user_chats,omitempty"`
+	AllowBotChats     bool              `json:"allow_bot_chats,omitempty"`
+	AllowGroupChats   bool              `json:"allow_group_chats,omitempty"`
+	AllowChannelChats bool              `json:"allow_channel_chats,omitempty"`
+}
+
+// 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 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 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

@@ -0,0 +1,47 @@
+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"`
+	WebApp         *WebAppInfo `json:"web_app,omitempty"`
+	StartParameter string      `json:"start_parameter,omitempty"`
+}
+
+// InputRichMessageContent represents the content of a rich message to be
+// sent as the result of an inline query. Use it as the input_message_content
+// value of an InlineQueryResult.
+// Since: Bot API 10.1
+// See https://core.telegram.org/bots/api#inputrichmessagecontent
+type InputRichMessageContent struct {
+	// RichMessage contains structured rich-message content.
+	RichMessage InputRichMessage `json:"rich_message"`
+}
+
+// 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/log_redaction.go

@@ -0,0 +1,57 @@
+package tgapi
+
+import (
+	"encoding/json"
+	"fmt"
+	"strings"
+)
+
+const redactedLogValue = "<REDACTED>"
+
+var sensitiveLogFields = map[string]struct{}{
+	"callback_data":    {},
+	"credentials":      {},
+	"data":             {},
+	"invoice_payload":  {},
+	"payload":          {},
+	"provider_data":    {},
+	"provider_token":   {},
+	"secret":           {},
+	"secret_token":     {},
+	"token":            {},
+	"web_app_query_id": {},
+}
+
+func redactRequestLog(data []byte) string {
+	var value any
+	if err := json.Unmarshal(data, &value); err != nil {
+		return fmt.Sprintf("<invalid JSON omitted: %d bytes>", len(data))
+	}
+	redactLogValue(value)
+	redacted, err := json.Marshal(value)
+	if err != nil {
+		return fmt.Sprintf("<unavailable JSON omitted: %d bytes>", len(data))
+	}
+	return string(redacted)
+}
+
+func redactLogValue(value any) {
+	switch value := value.(type) {
+	case map[string]any:
+		for key, item := range value {
+			if _, sensitive := sensitiveLogFields[strings.ToLower(key)]; sensitive {
+				value[key] = redactedLogValue
+				continue
+			}
+			redactLogValue(item)
+		}
+	case []any:
+		for _, item := range value {
+			redactLogValue(item)
+		}
+	}
+}
+
+func responseLogSummary(method string, size int) string {
+	return fmt.Sprintf("method=%s bytes=%d body=omitted", method, size)
+}

tgapi/log_redaction_test.go

@@ -0,0 +1,39 @@
+package tgapi
+
+import (
+	"strings"
+	"testing"
+)
+
+func TestRedactRequestLogRemovesSensitiveValues(t *testing.T) {
+	const input = `{"secret_token":"webhook-secret","provider_token":"payment-token","nested":{"data":"passport-data","callback_data":"callback-secret"},"chat_id":42}`
+	got := redactRequestLog([]byte(input))
+
+	for _, secret := range []string{"webhook-secret", "payment-token", "passport-data", "callback-secret"} {
+		if strings.Contains(got, secret) {
+			t.Errorf("redacted request contains %q: %s", secret, got)
+		}
+	}
+	if !strings.Contains(got, `"chat_id":42`) {
+		t.Errorf("redacted request lost non-sensitive field: %s", got)
+	}
+}
+
+func TestRedactRequestLogOmitsInvalidJSON(t *testing.T) {
+	const secret = "not-json-secret"
+	got := redactRequestLog([]byte(secret))
+	if strings.Contains(got, secret) {
+		t.Fatalf("invalid JSON was logged verbatim: %s", got)
+	}
+}
+
+func TestResponseLogSummaryNeverContainsBody(t *testing.T) {
+	const token = "managed-bot-token"
+	got := responseLogSummary("getManagedBotToken", len(token))
+	if strings.Contains(got, token) {
+		t.Fatalf("response summary contains response body: %s", got)
+	}
+	if !strings.Contains(got, "body=omitted") {
+		t.Fatalf("response summary does not explain omission: %s", got)
+	}
+}

tgapi/messages_types.go

@@ -1,81 +1,395 @@
 package tgapi
 
-import "git.nix13.pw/scuroneko/extypes"
+import (
+	"encoding/json"
 
-type MessageReplyMarkup struct {
-	InlineKeyboard [][]InlineKeyboardButton `json:"inline_keyboard"`
+	"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"`
 }
 
+// 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 identifies a known user origin.
+	MessageOriginUserType = "user"
+	// MessageOriginHiddenUserType identifies a hidden user origin.
+	MessageOriginHiddenUserType = "hidden_user"
+	// MessageOriginChatType identifies a chat origin.
+	MessageOriginChatType = "chat"
+	// MessageOriginChannel identifies a channel origin.
+	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"`
-	MessageThreadID      int    `json:"message_thread_id,omitempty"`
-	BusinessConnectionId string `json:"business_connection_id,omitempty"`
-	From                 *User  `json:"from,omitempty"`
+	MessageID          int                 `json:"message_id"`
+	MessageThreadID    int                 `json:"message_thread_id,omitempty"`    // Since: Bot API 6.3
+	DirectMessageTopic *DirectMessageTopic `json:"direct_message_topic,omitempty"` // Since: Bot API 9.2
+	From               *User               `json:"from,omitempty"`
 
-	SenderChat        *Chat `json:"sender_chat,omitempty"`
-	SenderBoostCount  int   `json:"sender_boost_count,omitempty"`
-	SenderBusinessBot *User `json:"sender_business_bot,omitempty"`
-	Chat              *Chat `json:"chat,omitempty"`
+	SenderChat        *Chat  `json:"sender_chat,omitempty"`         // Since: Bot API 5.0
+	SenderBoostCount  int    `json:"sender_boost_count,omitempty"`  // Since: Bot API 7.1
+	SenderBusinessBot *User  `json:"sender_business_bot,omitempty"` // Since: Bot API 7.2
+	SenderTag         string `json:"sender_tag,omitempty"`          // Since: Bot API 9.5
+	// ReceiverUser identifies the user who can see the ephemeral message.
+	ReceiverUser *User `json:"receiver_user,omitempty"` // Since: Bot API 10.2
+	// EphemeralMessageID identifies the ephemeral message.
+	EphemeralMessageID   int64          `json:"ephemeral_message_id,omitempty"` // Since: Bot API 10.2
+	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"`
-	IsAutomaticForward bool     `json:"is_automatic_forward,omitempty"`
-	IsFromOffline      bool     `json:"is_from_offline,omitempty"`
-	IsPaidPost         bool     `json:"is_paid_post,omitempty"`
-	MediaGroupId       string   `json:"media_group_id,omitempty"`
-	AuthorSignature    string   `json:"author_signature,omitempty"`
-	PaidStarCount      int      `json:"paid_star_count,omitempty"`
-	ReplyToMessage     *Message `json:"reply_to_message,omitempty"`
+	IsTopicMessage     bool               `json:"is_topic_message,omitempty"`     // Since: Bot API 6.3
+	IsAutomaticForward bool               `json:"is_automatic_forward,omitempty"` // Since: Bot API 5.5
+	ReplyToMessage     *Message           `json:"reply_to_message,omitempty"`
+	ExternalReply      *ExternalReplyInfo `json:"external_reply,omitempty"` // Since: Bot API 7.0
+	Quote              *TextQuote         `json:"quote,omitempty"`          // Since: Bot API 7.0
 
-	Text string `json:"text"`
-
-	Photo           extypes.Slice[*PhotoSize] `json:"photo,omitempty"`
-	Caption         string                    `json:"caption,omitempty"`
-	CaptionEntities []MessageEntity           `json:"caption_entities,omitempty"`
-
-	Date     int `json:"date"`
-	EditDate int `json:"edit_date"`
-
-	ReplyMarkup *MessageReplyMarkup `json:"reply_markup,omitempty"`
+	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
+	ReplyToPollOptionID    string `json:"reply_to_poll_option_id,omitempty"`    // Since: Bot API 9.6
+	ViaBot                 *User  `json:"via_bot,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
+	EditDate               int    `json:"edit_date,omitempty"`             // Since: Bot API 2.1
+	HasProtectedContent    bool   `json:"has_protected_content,omitempty"` // Since: Bot API 5.5
+	IsFromOffline          bool   `json:"is_from_offline,omitempty"`       // Since: Bot API 7.2
+	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"`
+	// RichMessage contains structured rich-message content.
+	RichMessage           *RichMessage             `json:"rich_message,omitempty"` // Since: Bot API 10.1
+	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
+	// CommunityChatAdded describes a community chat addition service message.
+	CommunityChatAdded *CommunityChatAdded `json:"community_chat_added,omitempty"` // Since: Bot API 10.2
+	// CommunityChatRemoved describes a community chat removal service message.
+	CommunityChatRemoved      *CommunityChatRemoved      `json:"community_chat_removed,omitempty"`       // Since: Bot API 10.2
+	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"`
 	MessageID int  `json:"message_id"`
 	Date      int  `json:"date"`
 }
 
-type MaybeInaccessibleMessage interface{ Message | InaccessibleMessage }
+// 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 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
 
 const (
-	MessageEntityMention              MessageEntityType = "mention"
-	MessageEntityHashtag              MessageEntityType = "hashtag"
-	MessageEntityCashtag              MessageEntityType = "cashtag"
-	MessageEntityBotCommand           MessageEntityType = "bot_command"
-	MessageEntityUrl                  MessageEntityType = "url"
-	MessageEntityEmail                MessageEntityType = "email"
-	MessageEntityPhoneNumber          MessageEntityType = "phone_number"
-	MessageEntityBold                 MessageEntityType = "bold"
-	MessageEntityItalic               MessageEntityType = "italic"
-	MessageEntityUnderline            MessageEntityType = "underline"
-	MessageEntityStrike               MessageEntityType = "strikethrough"
-	MessageEntitySpoiler              MessageEntityType = "spoiler"
-	MessageEntityBlockquote           MessageEntityType = "blockquote"
-	MessageEntityExpandableBlockquote MessageEntityType = "expandable_blockquote"
-	MessageEntityCode                 MessageEntityType = "code"
-	MessageEntityPre                  MessageEntityType = "pre"
-	MessageEntityTextLink             MessageEntityType = "text_link"
-	MessageEntityTextMention          MessageEntityType = "text_mention"
-	MessageEntityCustomEmoji          MessageEntityType = "custom_emoji"
+	// MessageEntityMention identifies an @mention entity.
+	MessageEntityMention MessageEntityType = "mention"
+	// MessageEntityHashtag identifies a hashtag entity.
+	MessageEntityHashtag MessageEntityType = "hashtag"
+	// MessageEntityCashtag identifies a cashtag entity.
+	MessageEntityCashtag MessageEntityType = "cashtag"
+	// MessageEntityBotCommand identifies a bot command entity.
+	MessageEntityBotCommand MessageEntityType = "bot_command"
+	// MessageEntityURL identifies a URL entity.
+	MessageEntityURL MessageEntityType = "url"
+	// MessageEntityEmail identifies an email entity.
+	MessageEntityEmail MessageEntityType = "email"
+	// MessageEntityPhoneNumber identifies a phone number entity.
+	MessageEntityPhoneNumber MessageEntityType = "phone_number"
+	// MessageEntityBold identifies bold text.
+	MessageEntityBold MessageEntityType = "bold"
+	// MessageEntityItalic identifies italic text.
+	MessageEntityItalic MessageEntityType = "italic"
+	// MessageEntityUnderline identifies underlined text.
+	MessageEntityUnderline MessageEntityType = "underline"
+	// MessageEntityStrike identifies strikethrough text.
+	MessageEntityStrike MessageEntityType = "strikethrough"
+	// MessageEntitySpoiler identifies spoiler text.
+	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" // Since: Bot API 7.5
+	// MessageEntityCode identifies inline code.
+	MessageEntityCode MessageEntityType = "code"
+	// MessageEntityPre identifies a preformatted block.
+	MessageEntityPre MessageEntityType = "pre"
+	// MessageEntityTextLink identifies linked text.
+	MessageEntityTextLink MessageEntityType = "text_link"
+	// MessageEntityTextMention identifies a text mention.
+	MessageEntityTextMention MessageEntityType = "text_mention"
+	// MessageEntityCustomEmoji identifies a custom emoji entity.
+	MessageEntityCustomEmoji MessageEntityType = "custom_emoji" // Since: Bot API 6.2
+	// MessageEntityDateTime identifies a date-time entity.
+	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"`
 
@@ -84,21 +398,33 @@ 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       int64  `json:"unix_time,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"`
-	ChatID    int `json:"chat_id,omitempty"`
+	MessageID int   `json:"message_id,omitempty"`
+	ChatID    int64 `json:"chat_id,omitempty"`
+	// EphemeralMessageID identifies the ephemeral message.
+	EphemeralMessageID int64 `json:"ephemeral_message_id,omitempty"` // Since: Bot API 10.2
 
-	AllowSendingWithoutReply bool             `json:"allow_sending_without_reply,omitempty"`
-	Quote                    string           `json:"quote,omitempty"`
-	QuoteParsingMode         string           `json:"quote_parsing_mode,omitempty"`
-	QuoteEntities            []*MessageEntity `json:"quote_entities,omitempty"`
-	QuotePosition            int              `json:"quote_position,omitempty"`
-	ChecklistTaskID          int              `json:"checklist_task_id,omitempty"`
+	AllowSendingWithoutReply bool            `json:"allow_sending_without_reply,omitempty"`
+	Quote                    string          `json:"quote,omitempty"`
+	QuoteParsingMode         string          `json:"quote_parsing_mode,omitempty"`
+	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"`
 	URL              string `json:"url,omitempty"`
@@ -107,85 +433,168 @@ type LinkPreviewOptions struct {
 	ShowAboveText    bool   `json:"show_above_text,omitempty"`
 }
 
+// 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"`
 
-	Keyboard              [][]int `json:"keyboard,omitempty"`
-	IsPersistent          bool    `json:"is_persistent,omitempty"`
-	ResizeKeyboard        bool    `json:"resize_keyboard,omitempty"`
-	OneTimeKeyboard       bool    `json:"one_time_keyboard,omitempty"`
-	InputFieldPlaceholder string  `json:"input_field_placeholder,omitempty"`
-	Selective             bool    `json:"selective,omitempty"`
+	Keyboard              [][]KeyboardButton `json:"keyboard,omitempty"`
+	IsPersistent          bool               `json:"is_persistent,omitempty"`
+	ResizeKeyboard        bool               `json:"resize_keyboard,omitempty"`
+	OneTimeKeyboard       bool               `json:"one_time_keyboard,omitempty"`
+	InputFieldPlaceholder string             `json:"input_field_placeholder,omitempty"`
+	Selective             bool               `json:"selective,omitempty"`
 
 	RemoveKeyboard bool `json:"remove_keyboard,omitempty"`
 
 	ForceReply bool `json:"force_reply,omitempty"`
 }
+
+// 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"`
 }
 
+// KeyboardButtonStyle represents the style of a keyboard button.
 type KeyboardButtonStyle string
+
+const (
+	// KeyboardButtonStyleDanger marks a destructive keyboard button.
+	KeyboardButtonStyleDanger KeyboardButtonStyle = "danger"
+	// KeyboardButtonStyleSuccess marks a confirmatory keyboard button.
+	KeyboardButtonStyleSuccess KeyboardButtonStyle = "success"
+	// KeyboardButtonStylePrimary marks a primary keyboard button.
+	KeyboardButtonStylePrimary KeyboardButtonStyle = "primary"
+)
+
+// 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"`
+	IconCustomEmojiID string                           `json:"icon_custom_emoji_id,omitempty"` // Since: Bot API 9.4
+	Style             KeyboardButtonStyle              `json:"style,omitempty"`                // Since: Bot API 9.4
+	RequestUsers      *KeyboardButtonRequestUsers      `json:"request_users,omitempty"`        // Since: Bot API 7.0
+	RequestChat       *KeyboardButtonRequestChat       `json:"request_chat,omitempty"`         // Since: Bot API 6.5
+	RequestManagedBot *KeyboardButtonRequestManagedBot `json:"request_managed_bot,omitempty"`  // Since: Bot API 9.6
+	RequestContact    bool                             `json:"request_contact,omitempty"`
+	RequestLocation   bool                             `json:"request_location,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"`
+	UserIsBot       *bool `json:"user_is_bot,omitempty"`
+	UserIsPremium   *bool `json:"user_is_premium,omitempty"`
+	MaxQuantity     int   `json:"max_quantity,omitempty"`
+	RequestName     bool  `json:"request_name,omitempty"`
+	RequestUsername bool  `json:"request_username,omitempty"`
+	RequestPhoto    bool  `json:"request_photo,omitempty"`
+}
+
+// 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"`
+	ChatIsChannel           bool                     `json:"chat_is_channel"`
+	ChatIsForum             *bool                    `json:"chat_is_forum,omitempty"`
+	ChatHasUsername         *bool                    `json:"chat_has_username,omitempty"`
+	ChatIsCreated           *bool                    `json:"chat_is_created,omitempty"`
+	UserAdministratorRights *ChatAdministratorRights `json:"user_administrator_rights,omitempty"`
+	BotAdministratorRights  *ChatAdministratorRights `json:"bot_administrator_rights,omitempty"`
+	BotIsMember             bool                     `json:"bot_is_member,omitempty"`
+	RequestTitle            bool                     `json:"request_title,omitempty"`
+	RequestUsername         bool                     `json:"request_username,omitempty"`
+	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"`
-	IconCustomEmojiID string              `json:"icon_custom_emoji_id,omitempty"`
+	Style             KeyboardButtonStyle `json:"style,omitempty"`                // Since: Bot API 9.4
+	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 [][]int `json:"keyboard"`
+	Keyboard              [][]KeyboardButton `json:"keyboard"`
+	IsPersistent          bool               `json:"is_persistent,omitempty"`
+	ResizeKeyboard        bool               `json:"resize_keyboard,omitempty"`
+	OneTimeKeyboard       bool               `json:"one_time_keyboard,omitempty"`
+	InputFieldPlaceholder string             `json:"input_field_placeholder,omitempty"`
+	Selective             bool               `json:"selective,omitempty"`
 }
 
+// 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"`
-	From    User    `json:"from"`
-	Message Message `json:"message"`
-
-	Data string `json:"data"`
-}
-
-type InputPollOption struct {
-	Text          string           `json:"text"`
-	TextParseMode ParseMode        `json:"text_parse_mode,omitempty"`
-	TextEntities  []*MessageEntity `json:"text_entities,omitempty"`
-}
-type PollType string
-
-const (
-	PollTypeRegular PollType = "regular"
-	PollTypeQuiz    PollType = "quiz"
-)
-
-type InputChecklistTask struct {
-	ID           int              `json:"id"`
-	Text         string           `json:"text"`
-	ParseMode    ParseMode        `json:"parse_mode,omitempty"`
-	TextEntities []*MessageEntity `json:"text_entities,omitempty"`
-}
-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"`
+	ID              string   `json:"id"`
+	From            User     `json:"from"`
+	Message         *Message `json:"message,omitempty"`
+	InlineMessageID *string  `json:"inline_message_id,omitempty"`
+	ChatInstance    string   `json:"chat_instance,omitempty"`
+	Data            string   `json:"data,omitempty"`
+	GameShortName   string   `json:"game_short_name,omitempty"`
 }
 
+// ChatActionType represents the type of chat action.
 type ChatActionType string
 
 const (
-	ChatActionTyping          ChatActionType = "typing"
-	ChatActionUploadPhoto     ChatActionType = "upload_photo"
-	ChatActionUploadVideo     ChatActionType = "upload_video"
-	ChatActionUploadVoice     ChatActionType = "upload_voice"
-	ChatActionUploadDocument  ChatActionType = "upload_document"
-	ChatActionChooseSticker   ChatActionType = "choose_sticker"
-	ChatActionFindLocation    ChatActionType = "find_location"
-	ChatActionUploadVideoNone ChatActionType = "upload_video_none"
+	// ChatActionTyping tells Telegram the bot is typing.
+	ChatActionTyping ChatActionType = "typing"
+	// ChatActionUploadPhoto tells Telegram the bot is uploading a photo.
+	ChatActionUploadPhoto ChatActionType = "upload_photo"
+	// ChatActionUploadVideo tells Telegram the bot is uploading a video.
+	ChatActionUploadVideo ChatActionType = "upload_video"
+	// ChatActionUploadVoice tells Telegram the bot is uploading a voice message.
+	ChatActionUploadVoice ChatActionType = "upload_voice"
+	// ChatActionUploadDocument tells Telegram the bot is uploading a document.
+	ChatActionUploadDocument ChatActionType = "upload_document"
+	// ChatActionChooseSticker tells Telegram the bot is choosing a sticker.
+	ChatActionChooseSticker ChatActionType = "choose_sticker"
+	// ChatActionFindLocation tells Telegram the bot is finding a location.
+	ChatActionFindLocation ChatActionType = "find_location"
+	// ChatActionUploadVideoNote tells Telegram the bot is uploading a video note.
+	ChatActionUploadVideoNote ChatActionType = "upload_video_note"
+	// ChatActionUploadVideoNone is a deprecated alias for 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"`
 	MessageID   int            `json:"message_id"`
@@ -196,12 +605,19 @@ type MessageReactionUpdated struct {
 	NewReaction []ReactionType `json:"new_reaction"`
 }
 
+// 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"`
 	MessageID int              `json:"message_id"`
 	Date      int              `json:"date"`
 	Reactions []*ReactionCount `json:"reactions"`
 }
+
+// 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"`
 	// ReactionTypeEmoji
@@ -209,21 +625,179 @@ type ReactionType struct {
 	// ReactionTypeCustomEmoji
 	CustomEmojiID *string `json:"custom_emoji_id,omitempty"`
 }
+
+// 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"`
 	TotalCount int          `json:"total_count"`
 }
 
+// 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"` //State of the suggested post. Currently, it can be one of “pending”, “approved”, “declined”.
+	State    string             `json:"state"` // "pending", "approved", or "declined"
 	Price    SuggestedPostPrice `json:"price"`
 	SendDate int                `json:"send_date"`
 }
+
+// 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"`
+}
+
+// RichMessage represents a received rich-formatted message.
+// Since: Bot API 10.1
+type RichMessage struct {
+	// Blocks contains the nested rich-message blocks.
+	Blocks []RichBlock `json:"blocks"`
+	// IsRTL requests right-to-left rich-message layout.
+	IsRTL bool `json:"is_rtl,omitempty"`
+}
+
+// InputRichMessageMedia describes media embedded in outgoing rich-message HTML or Markdown.
+//
+// Since: Bot API 10.2
+type InputRichMessageMedia struct {
+	// ID uniquely identifies the value within its containing object.
+	ID string `json:"id"`
+	// Media contains or identifies media associated with the value.
+	Media InputMedia `json:"media"`
+}
+
+// InputRichMessage describes a rich message to be sent. Exactly one of HTML, Markdown, or Blocks must be used.
+//
+// Since: Bot API 10.1
+type InputRichMessage struct {
+	// Blocks contains the nested rich-message blocks.
+	Blocks []InputRichBlock `json:"blocks,omitempty"` // Since: Bot API 10.2
+	// HTML contains rich-message content in Telegram HTML syntax.
+	HTML string `json:"html,omitempty"`
+	// Markdown contains rich-message content in Telegram Markdown syntax.
+	Markdown string `json:"markdown,omitempty"`
+	// Media contains or identifies media associated with the value.
+	Media []InputRichMessageMedia `json:"media,omitempty"` // Since: Bot API 10.2
+	// IsRTL requests right-to-left rich-message layout.
+	IsRTL bool `json:"is_rtl,omitempty"`
+	// SkipEntityDetection disables automatic detection of links, mentions, hashtags, commands, phone numbers, and bank cards.
+	SkipEntityDetection bool `json:"skip_entity_detection,omitempty"`
+}

tgapi/messages_types_test.go

@@ -0,0 +1,37 @@
+package tgapi
+
+import (
+	"encoding/json"
+	"strings"
+	"testing"
+)
+
+func TestReplyKeyboardMarkupMarshalsKeyboardButtons(t *testing.T) {
+	markup := ReplyKeyboardMarkup{
+		Keyboard: [][]KeyboardButton{{
+			{
+				Text:        "Create poll",
+				RequestPoll: &KeyboardButtonPollType{Type: PollTypeQuiz},
+			},
+		}},
+	}
+
+	data, err := json.Marshal(markup)
+	if err != nil {
+		t.Fatalf("Marshal returned error: %v", err)
+	}
+
+	got := string(data)
+	if !strings.Contains(got, `"keyboard":[[{"text":"Create poll","request_poll":{"type":"quiz"}}]]`) {
+		t.Fatalf("unexpected reply keyboard JSON: %s", got)
+	}
+}
+
+func TestChatActionUploadVideoNoteValue(t *testing.T) {
+	if ChatActionUploadVideoNote != "upload_video_note" {
+		t.Fatalf("unexpected chat action value: %q", ChatActionUploadVideoNote)
+	}
+	if ChatActionUploadVideoNone != ChatActionUploadVideoNote {
+		t.Fatalf("expected deprecated alias to match upload_video_note, got %q", ChatActionUploadVideoNone)
+	}
+}

tgapi/methods.go

@@ -1,46 +1,282 @@
 package tgapi
 
-type ParseMode string
+import (
+	"context"
+	"fmt"
+	"io"
+	"net/http"
 
-const (
-	ParseMDV2 ParseMode = "MarkdownV2"
-	ParseHTML ParseMode = "HTML"
-	ParseMD   ParseMode = "Markdown"
+	"git.scuroneko.dev/scuroneko/laniakea/utils"
 )
 
-type EmptyParams struct{}
-
-var NoParams = EmptyParams{}
-
+// UpdateParams holds parameters for the getUpdates method.
+// See https://core.telegram.org/bots/api#getupdates
 type UpdateParams struct {
 	Offset         *int         `json:"offset,omitempty"`
 	Limit          *int         `json:"limit,omitempty"`
 	Timeout        *int         `json:"timeout,omitempty"`
-	AllowedUpdates []UpdateType `json:"allowed_updates"`
+	AllowedUpdates []UpdateType `json:"allowed_updates,omitempty"`
 }
 
+// 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)
 }
+
+// GetMeWithContext is the context-aware variant of GetMe.
+// 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]("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)
+}
+
+// LogOut logs the bot out from the cloud Bot API server.
+// Returns true on success.
+// See https://core.telegram.org/bots/api#logout
 func (api *API) LogOut() (bool, error) {
-	req := NewRequest[bool, EmptyParams]("logOut", NoParams)
+	req := NewRequest[bool]("logOut", NoParams)
 	return req.Do(api)
 }
-func (api *API) Close() (bool, error) {
-	req := NewRequest[bool, EmptyParams]("close", NoParams)
+
+// LogOutWithContext is the context-aware variant of LogOut.
+// It executes the same request but uses ctx for cancellation and deadlines.
+// See https://core.telegram.org/bots/api#logout
+func (api *API) LogOutWithContext(ctx context.Context) (bool, error) {
+	req := NewRequest[bool]("logOut", NoParams)
+	return req.DoWithContext(ctx, api)
+}
+
+// CloseRemote closes the bot instance on the local server.
+// Returns true on success.
+// See https://core.telegram.org/bots/api#close
+func (api *API) CloseRemote() (bool, error) {
+	req := NewRequest[bool]("close", NoParams)
 	return req.Do(api)
 }
+
+// CloseRemoteWithContext is the context-aware variant of CloseRemote.
+// It executes the same request but uses ctx for cancellation and deadlines.
+// See https://core.telegram.org/bots/api#close
+func (api *API) CloseRemoteWithContext(ctx context.Context) (bool, error) {
+	req := NewRequest[bool]("close", NoParams)
+	return req.DoWithContext(ctx, api)
+}
+
+// GetUpdates receives incoming updates using long polling.
+// See https://core.telegram.org/bots/api#getupdates
 func (api *API) GetUpdates(params UpdateParams) ([]Update, error) {
 	req := NewRequest[[]Update]("getUpdates", params)
 	return req.Do(api)
 }
 
-type GetFileP struct {
-	FileId string `json:"file_id"`
+// GetUpdatesWithContext is the context-aware variant of GetUpdates.
+// It executes the same request but uses ctx for cancellation and deadlines.
+// See https://core.telegram.org/bots/api#getupdates
+func (api *API) GetUpdatesWithContext(ctx context.Context, params UpdateParams) ([]Update, error) {
+	req := NewRequest[[]Update]("getUpdates", params)
+	return req.DoWithContext(ctx, api)
 }
 
-func (api *API) GetFile(params GetFileP) (File, error) {
+// 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 SetWebhook struct {
+	URL                string       `json:"url"`
+	IPAddress          string       `json:"ip_address,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 sets a webhook URL for incoming updates.
+// For certificate upload, use Uploader.SetWebhook.
+// Returns true on success.
+// See https://core.telegram.org/bots/api#setwebhook
+func (api *API) SetWebhook(params SetWebhook) (bool, error) {
+	req := NewRequest[bool]("setWebhook", params)
+	return req.Do(api)
+}
+
+// SetWebhookWithContext is the context-aware variant of SetWebhook.
+// 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 SetWebhook) (bool, error) {
+	req := NewRequest[bool]("setWebhook", params)
+	return req.DoWithContext(ctx, api)
+}
+
+// DeleteWebhook holds parameters for the deleteWebhook method.
+// See https://core.telegram.org/bots/api#deletewebhook
+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 DeleteWebhook) (bool, error) {
+	req := NewRequest[bool]("deleteWebhook", params)
+	return req.Do(api)
+}
+
+// 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 DeleteWebhook) (bool, error) {
+	req := NewRequest[bool]("deleteWebhook", params)
+	return req.DoWithContext(ctx, api)
+}
+
+// GetWebhookInfo returns the current webhook status.
+// See https://core.telegram.org/bots/api#getwebhookinfo
+func (api *API) GetWebhookInfo() (WebhookInfo, error) {
+	req := NewRequest[WebhookInfo]("getWebhookInfo", NoParams)
+	return req.Do(api)
+}
+
+// GetWebhookInfoWithContext is the context-aware variant of GetWebhookInfo.
+// It executes the same request but uses ctx for cancellation and deadlines.
+// See https://core.telegram.org/bots/api#getwebhookinfo
+func (api *API) GetWebhookInfoWithContext(ctx context.Context) (WebhookInfo, error) {
+	req := NewRequest[WebhookInfo]("getWebhookInfo", NoParams)
+	return req.DoWithContext(ctx, api)
+}
+
+// GetFile holds parameters for the getFile method.
+// See https://core.telegram.org/bots/api#getfile
+type GetFile struct {
+	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 GetFile) (File, error) {
 	req := NewRequest[File]("getFile", params)
 	return req.Do(api)
 }
+
+// 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 GetFile) (File, error) {
+	req := NewRequest[File]("getFile", params)
+	return req.DoWithContext(ctx, api)
+}
+
+// GetFileByLink downloads a file from Telegram's file server using the provided file link.
+// The link is usually obtained from File.FilePath.
+// For large files, prefer OpenFileByLink or OpenFileByLinkWithContext to stream the response body.
+// See https://core.telegram.org/bots/api#file
+func (api *API) GetFileByLink(link string) ([]byte, error) {
+	return api.getFileByLink(context.Background(), link)
+}
+
+// GetFileByLinkWithContext is the context-aware variant of GetFileByLink.
+// It executes the same request but uses ctx for cancellation and deadlines.
+// For large files, prefer OpenFileByLinkWithContext to stream the response body.
+// See https://core.telegram.org/bots/api#file
+func (api *API) GetFileByLinkWithContext(ctx context.Context, link string) ([]byte, error) {
+	return api.getFileByLink(ctx, link)
+}
+
+// OpenFileByLink opens a streaming response body for a file hosted on Telegram's file server.
+// The caller must close the returned ReadCloser.
+// See https://core.telegram.org/bots/api#file
+func (api *API) OpenFileByLink(link string) (io.ReadCloser, error) {
+	return api.openFileByLink(context.Background(), link)
+}
+
+// OpenFileByLinkWithContext is the context-aware variant of OpenFileByLink.
+// The caller must close the returned ReadCloser.
+// See https://core.telegram.org/bots/api#file
+func (api *API) OpenFileByLinkWithContext(ctx context.Context, link string) (io.ReadCloser, error) {
+	return api.openFileByLink(ctx, link)
+}
+
+func (api *API) getFileByLink(ctx context.Context, link string) ([]byte, error) {
+	body, err := api.openFileByLink(ctx, link)
+	if err != nil {
+		return nil, err
+	}
+	defer func() {
+		_ = body.Close()
+	}()
+	return io.ReadAll(body)
+}
+
+func (api *API) openFileByLink(ctx context.Context, link string) (io.ReadCloser, error) {
+	methodPrefix := ""
+	if api.useTestServer {
+		methodPrefix = "/test"
+	}
+	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 {
+		return nil, err
+	}
+	req.Header.Set("User-Agent", fmt.Sprintf("Laniakea/%s", utils.VersionString))
+
+	res, err := api.client.Do(req)
+	if err != nil {
+		return nil, err
+	}
+	if res.StatusCode < http.StatusOK || res.StatusCode >= http.StatusMultipleChoices {
+		defer func() {
+			_ = res.Body.Close()
+		}()
+		body, readErr := io.ReadAll(io.LimitReader(res.Body, 4<<10))
+		if readErr != nil {
+			return nil, fmt.Errorf("unexpected status %d", res.StatusCode)
+		}
+		return nil, fmt.Errorf("unexpected status %d: %s", res.StatusCode, string(body))
+	}
+	return res.Body, nil
+}

tgapi/methods_test.go

@@ -0,0 +1,210 @@
+package tgapi
+
+import (
+	"encoding/json"
+	"io"
+	"net/http"
+	"strings"
+	"testing"
+)
+
+func TestGetFileByLinkUsesConfiguredAPIURL(t *testing.T) {
+	var gotPath string
+
+	client := &http.Client{
+		Transport: roundTripFunc(func(req *http.Request) (*http.Response, error) {
+			gotPath = req.URL.Path
+			return &http.Response{
+				StatusCode: http.StatusOK,
+				Body:       io.NopCloser(strings.NewReader("payload")),
+			}, 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)
+		}
+	}()
+
+	data, err := api.GetFileByLink("files/report.txt")
+	if err != nil {
+		t.Fatalf("GetFileByLink returned error: %v", err)
+	}
+	if string(data) != "payload" {
+		t.Fatalf("unexpected payload: %q", string(data))
+	}
+	if gotPath != "/file/bottoken/files/report.txt" {
+		t.Fatalf("unexpected request path: %s", gotPath)
+	}
+}
+
+func TestOpenFileByLinkStreamsResponseBody(t *testing.T) {
+	api := NewAPI(
+		NewAPIOpts("token").
+			SetAPIURL("https://example.test").
+			SetHTTPClient(&http.Client{
+				Transport: roundTripFunc(func(req *http.Request) (*http.Response, error) {
+					return &http.Response{
+						StatusCode: http.StatusOK,
+						Body:       io.NopCloser(strings.NewReader("streamed payload")),
+					}, nil
+				}),
+			}),
+	)
+	defer func() {
+		if err := api.Close(); err != nil {
+			t.Fatalf("Close returned error: %v", err)
+		}
+	}()
+
+	body, err := api.OpenFileByLink("files/report.txt")
+	if err != nil {
+		t.Fatalf("OpenFileByLink returned error: %v", err)
+	}
+	defer func() {
+		if err := body.Close(); err != nil {
+			t.Fatalf("Close returned error: %v", err)
+		}
+	}()
+
+	data, err := io.ReadAll(body)
+	if err != nil {
+		t.Fatalf("failed to read body: %v", err)
+	}
+	if string(data) != "streamed payload" {
+		t.Fatalf("unexpected payload: %q", string(data))
+	}
+}
+
+func TestGetFileByLinkReturnsHTTPStatusError(t *testing.T) {
+	client := &http.Client{
+		Transport: roundTripFunc(func(req *http.Request) (*http.Response, error) {
+			return &http.Response{
+				StatusCode: http.StatusNotFound,
+				Body:       io.NopCloser(strings.NewReader("missing\n")),
+			}, 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)
+		}
+	}()
+
+	_, err := api.GetFileByLink("files/report.txt")
+	if err == nil {
+		t.Fatal("expected error for non-2xx response")
+	}
+}
+
+func TestGetUpdatesOmitsAllowedUpdatesWhenEmpty(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":[]}`)),
+			}, 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)
+		}
+	}()
+
+	updates, err := api.GetUpdates(UpdateParams{})
+	if err != nil {
+		t.Fatalf("GetUpdates returned error: %v", err)
+	}
+	if len(updates) != 0 {
+		t.Fatalf("expected no updates, got %d", len(updates))
+	}
+	if _, exists := gotBody["allowed_updates"]; exists {
+		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

@@ -0,0 +1,21 @@
+package tgapi
+
+// ParseMode represents the text formatting mode for message parsing.
+type ParseMode string
+
+const (
+	// ParseMarkdownV2 enables MarkdownV2 style parsing.
+	ParseMarkdownV2 ParseMode = "MarkdownV2"
+	// ParseHTML enables HTML style parsing.
+	ParseHTML ParseMode = "HTML"
+	// ParseMarkdown enables legacy Markdown style parsing.
+	ParseMarkdown ParseMode = "Markdown"
+	// ParseNone disables parse_mode and leaves plain-text requests unannotated.
+	ParseNone ParseMode = ""
+)
+
+// EmptyParams is a placeholder for methods that take no parameters.
+type EmptyParams struct{}
+
+// NoParams is a convenient instance of EmptyParams.
+var NoParams = EmptyParams{}

tgapi/parse_mode_test.go

@@ -0,0 +1,37 @@
+package tgapi
+
+import (
+	"encoding/json"
+	"strings"
+	"testing"
+)
+
+func TestParseNoneOmitsParseModeInJSON(t *testing.T) {
+	data, err := json.Marshal(SendMessage{
+		ChatID:    42,
+		Text:      "hello",
+		ParseMode: ParseNone,
+	})
+	if err != nil {
+		t.Fatalf("Marshal returned error: %v", err)
+	}
+
+	if strings.Contains(string(data), `"parse_mode"`) {
+		t.Fatalf("expected parse_mode to be omitted, got %s", string(data))
+	}
+}
+
+func TestParseModeStillSerializesExplicitModes(t *testing.T) {
+	data, err := json.Marshal(SendMessage{
+		ChatID:    42,
+		Text:      "hello",
+		ParseMode: ParseMarkdownV2,
+	})
+	if err != nil {
+		t.Fatalf("Marshal returned error: %v", err)
+	}
+
+	if !strings.Contains(string(data), `"parse_mode":"MarkdownV2"`) {
+		t.Fatalf("expected MarkdownV2 parse_mode, got %s", string(data))
+	}
+}

tgapi/passport_methods.go

@@ -0,0 +1,29 @@
+package tgapi
+
+import "context"
+
+// SetPassportDataErrors holds parameters for the setPassportDataErrors method.
+// Since: Bot API 4.0
+// See https://core.telegram.org/bots/api#setpassportdataerrors
+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 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 SetPassportDataErrors) (bool, error) {
+	req := NewRequest[bool]("setPassportDataErrors", params)
+	return req.DoWithContext(ctx, api)
+}

tgapi/passport_types.go

@@ -0,0 +1,90 @@
+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 identifies personal details.
+	PassportPersonalDetailsType PassportElementType = "personal_details"
+	// PassportPassportType identifies an international passport.
+	PassportPassportType PassportElementType = "passport"
+	// PassportDriverLicenseType identifies a driver license.
+	PassportDriverLicenseType PassportElementType = "driver_license"
+	// PassportIdentityCardType identifies an identity card.
+	PassportIdentityCardType PassportElementType = "identity_card"
+	// PassportInternalPassportType identifies an internal passport.
+	PassportInternalPassportType PassportElementType = "internal_passport"
+	// PassportAddressType identifies a residential address.
+	PassportAddressType PassportElementType = "address"
+	// PassportUtilityBillType identifies a utility bill.
+	PassportUtilityBillType PassportElementType = "utility_bill"
+	// PassportBankStatementType identifies a bank statement.
+	PassportBankStatementType PassportElementType = "bank_statement"
+	// PassportRentalAgreementType identifies a rental agreement.
+	PassportRentalAgreementType PassportElementType = "rental_agreement"
+	// PassportPassportRegistrationType identifies a passport registration.
+	PassportPassportRegistrationType PassportElementType = "passport_registration"
+	// PassportTemporaryRegistrationType identifies a temporary registration.
+	PassportTemporaryRegistrationType PassportElementType = "temporary_registration"
+	// PassportPhoneNumberType identifies a phone number.
+	PassportPhoneNumberType PassportElementType = "phone_number"
+	// PassportEmailType identifies an email address.
+	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 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

@@ -0,0 +1,162 @@
+package tgapi
+
+import "context"
+
+// SendInvoice holds parameters for the sendInvoice method.
+// Since: Bot API 3.0
+// See https://core.telegram.org/bots/api#sendinvoice
+type SendInvoice struct {
+	ChatID                int64 `json:"chat_id"`
+	MessageThreadID       int   `json:"message_thread_id,omitempty"`
+	DirectMessagesTopicID int   `json:"direct_messages_topic_id,omitempty"`
+
+	Title         string         `json:"title"`
+	Description   string         `json:"description"`
+	Payload       string         `json:"payload"`
+	ProviderToken string         `json:"provider_token,omitempty"`
+	Currency      string         `json:"currency"`
+	Prices        []LabeledPrice `json:"prices"`
+
+	MaxTipAmount        int    `json:"max_tip_amount,omitempty"`
+	SuggestedTipAmounts []int  `json:"suggested_tip_amounts,omitempty"`
+	StartParameter      string `json:"start_parameter,omitempty"`
+	ProviderData        string `json:"provider_data,omitempty"`
+	PhotoURL            string `json:"photo_url,omitempty"`
+	PhotoSize           int    `json:"photo_size,omitempty"`
+	PhotoWidth          int    `json:"photo_width,omitempty"`
+	PhotoHeight         int    `json:"photo_height,omitempty"`
+	NeedName            bool   `json:"need_name,omitempty"`
+	NeedPhoneNumber     bool   `json:"need_phone_number,omitempty"`
+	NeedEmail           bool   `json:"need_email,omitempty"`
+	NeedShippingAddress bool   `json:"need_shipping_address,omitempty"`
+	SendPhoneToProvider bool   `json:"send_phone_number_to_provider,omitempty"`
+	SendEmailToProvider bool   `json:"send_email_to_provider,omitempty"`
+	IsFlexible          bool   `json:"is_flexible,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             *InlineKeyboardMarkup    `json:"reply_markup,omitempty"`
+}
+
+// SendInvoice sends an invoice.
+// Since: Bot API 3.0
+// See https://core.telegram.org/bots/api#sendinvoice
+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 SendInvoice) (Message, error) {
+	req := NewRequestWithChatID[Message]("sendInvoice", params, params.ChatID)
+	return req.DoWithContext(ctx, api)
+}
+
+// CreateInvoiceLink holds parameters for the createInvoiceLink method.
+// Since: Bot API 6.1
+// See https://core.telegram.org/bots/api#createinvoicelink
+type CreateInvoiceLink struct {
+	BusinessConnectionID string `json:"business_connection_id,omitempty"`
+
+	Title         string         `json:"title"`
+	Description   string         `json:"description"`
+	Payload       string         `json:"payload"`
+	ProviderToken string         `json:"provider_token,omitempty"`
+	Currency      string         `json:"currency"`
+	Prices        []LabeledPrice `json:"prices"`
+
+	SubscriptionPeriod  int    `json:"subscription_period,omitempty"`
+	MaxTipAmount        int    `json:"max_tip_amount,omitempty"`
+	SuggestedTipAmounts []int  `json:"suggested_tip_amounts,omitempty"`
+	ProviderData        string `json:"provider_data,omitempty"`
+	PhotoURL            string `json:"photo_url,omitempty"`
+	PhotoSize           int    `json:"photo_size,omitempty"`
+	PhotoWidth          int    `json:"photo_width,omitempty"`
+	PhotoHeight         int    `json:"photo_height,omitempty"`
+	NeedName            bool   `json:"need_name,omitempty"`
+	NeedPhoneNumber     bool   `json:"need_phone_number,omitempty"`
+	NeedEmail           bool   `json:"need_email,omitempty"`
+	NeedShippingAddress bool   `json:"need_shipping_address,omitempty"`
+	SendPhoneToProvider bool   `json:"send_phone_number_to_provider,omitempty"`
+	SendEmailToProvider bool   `json:"send_email_to_provider,omitempty"`
+	IsFlexible          bool   `json:"is_flexible,omitempty"`
+}
+
+// CreateInvoiceLink creates an invoice link.
+// Since: Bot API 6.1
+// See https://core.telegram.org/bots/api#createinvoicelink
+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 CreateInvoiceLink) (string, error) {
+	req := NewRequest[string]("createInvoiceLink", params)
+	return req.DoWithContext(ctx, api)
+}
+
+// AnswerShippingQuery holds parameters for the answerShippingQuery method.
+// Since: Bot API 3.0
+// See https://core.telegram.org/bots/api#answershippingquery
+type AnswerShippingQuery struct {
+	ShippingQueryID string           `json:"shipping_query_id"`
+	OK              bool             `json:"ok"`
+	ShippingOptions []ShippingOption `json:"shipping_options,omitempty"`
+	ErrorMessage    string           `json:"error_message,omitempty"`
+}
+
+// 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 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 AnswerShippingQuery) (bool, error) {
+	req := NewRequest[bool]("answerShippingQuery", params)
+	return req.DoWithContext(ctx, api)
+}
+
+// AnswerPreCheckoutQuery holds parameters for the answerPreCheckoutQuery method.
+// Since: Bot API 3.0
+// See https://core.telegram.org/bots/api#answerprecheckoutquery
+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 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 AnswerPreCheckoutQuery) (bool, error) {
+	req := NewRequest[bool]("answerPreCheckoutQuery", params)
+	return req.DoWithContext(ctx, api)
+}

tgapi/payments_types.go

@@ -0,0 +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/pool.go

@@ -0,0 +1,135 @@
+package tgapi
+
+import (
+	"context"
+	"sync"
+)
+
+type workerPool struct {
+	taskCh    chan requestEnvelope
+	queueSize int
+	workers   int
+	wg        sync.WaitGroup
+	quit      chan struct{}
+	stopOnce  sync.Once
+	started   bool
+	stopped   bool
+	startedMu sync.Mutex
+}
+
+type requestEnvelope struct {
+	ctx      context.Context
+	doFunc   func(context.Context) (any, error)
+	resultCh chan requestResult
+}
+
+type requestResult struct {
+	value any
+	err   error
+}
+
+func newWorkerPool(workers int, queueSize int) *workerPool {
+	if workers <= 0 {
+		workers = 1
+	}
+	if queueSize <= 0 {
+		queueSize = 100
+	}
+
+	return &workerPool{
+		taskCh:    make(chan requestEnvelope, queueSize),
+		queueSize: queueSize,
+		workers:   workers,
+		quit:      make(chan struct{}),
+	}
+}
+
+func (p *workerPool) start() {
+	p.startedMu.Lock()
+	defer p.startedMu.Unlock()
+	if p.started {
+		return
+	}
+	p.started = true
+
+	for i := 0; i < p.workers; i++ {
+		p.wg.Add(1)
+		go p.worker()
+	}
+}
+
+func (p *workerPool) stop() {
+	p.stopOnce.Do(func() {
+		p.startedMu.Lock()
+		p.stopped = true
+		p.started = false
+		close(p.quit)
+		p.startedMu.Unlock()
+
+		p.wg.Wait()
+	})
+}
+
+func (p *workerPool) submit(ctx context.Context, do func(context.Context) (any, error)) (<-chan requestResult, error) {
+	p.startedMu.Lock()
+	if p.stopped || !p.started {
+		p.startedMu.Unlock()
+		return nil, ErrPoolStopped
+	}
+
+	if len(p.taskCh) >= p.queueSize {
+		p.startedMu.Unlock()
+		return nil, ErrPoolQueueFull
+	}
+
+	resultCh := make(chan requestResult, 1)
+
+	envelope := requestEnvelope{
+		ctx:      ctx,
+		doFunc:   do,
+		resultCh: resultCh,
+	}
+
+	select {
+	case <-ctx.Done():
+		p.startedMu.Unlock()
+		return nil, ctx.Err()
+	case p.taskCh <- envelope:
+		p.startedMu.Unlock()
+		return resultCh, nil
+	default:
+		p.startedMu.Unlock()
+		return nil, ErrPoolQueueFull
+	}
+}
+
+func (p *workerPool) worker() {
+	defer p.wg.Done()
+
+	for {
+		select {
+		case <-p.quit:
+			// Drain queued work after stop. No new tasks are accepted.
+			for {
+				select {
+				case envelope := <-p.taskCh:
+					p.executeEnvelope(envelope)
+				default:
+					return
+				}
+			}
+
+		case envelope := <-p.taskCh:
+			p.executeEnvelope(envelope)
+		}
+	}
+}
+
+func (p *workerPool) executeEnvelope(envelope requestEnvelope) {
+	value, err := envelope.doFunc(envelope.ctx)
+	envelope.resultCh <- requestResult{
+		value: value,
+		err:   err,
+	}
+	close(envelope.resultCh)
+}

tgapi/pool_test.go

@@ -0,0 +1,62 @@
+package tgapi
+
+import (
+	"context"
+	"errors"
+	"testing"
+)
+
+func TestWorkerPoolSubmitAfterStop(t *testing.T) {
+	pool := newWorkerPool(1, 1)
+	pool.start()
+	pool.stop()
+
+	if _, err := pool.submit(context.Background(), func(context.Context) (any, error) {
+		return nil, nil
+	}); !errors.Is(err, ErrPoolStopped) {
+		t.Fatalf("expected ErrPoolStopped, got %v", err)
+	}
+}
+
+func TestWorkerPoolQueueFull(t *testing.T) {
+	pool := newWorkerPool(1, 1)
+	pool.start()
+	defer pool.stop()
+
+	started := make(chan struct{})
+	release := make(chan struct{})
+
+	firstResult, err := pool.submit(context.Background(), func(context.Context) (any, error) {
+		close(started)
+		<-release
+		return "first", nil
+	})
+	if err != nil {
+		t.Fatalf("first submit returned error: %v", err)
+	}
+	<-started
+
+	secondResult, err := pool.submit(context.Background(), func(context.Context) (any, error) {
+		return "second", nil
+	})
+	if err != nil {
+		t.Fatalf("second submit returned error: %v", err)
+	}
+
+	if _, err := pool.submit(context.Background(), func(context.Context) (any, error) {
+		return "third", nil
+	}); !errors.Is(err, ErrPoolQueueFull) {
+		t.Fatalf("expected ErrPoolQueueFull, got %v", err)
+	}
+
+	close(release)
+
+	first := <-firstResult
+	if first.err != nil || first.value != "first" {
+		t.Fatalf("unexpected first result: %+v", first)
+	}
+	second := <-secondResult
+	if second.err != nil || second.value != "second" {
+		t.Fatalf("unexpected second result: %+v", second)
+	}
+}

tgapi/rich_block_types.go

@@ -0,0 +1,611 @@
+package tgapi
+
+import "encoding/json"
+
+// RichBlock is a block in a structured rich message.
+//
+// Since: Bot API 10.1
+type RichBlock interface {
+	isRichBlock()
+}
+
+// RichBlockCaption is the caption of a media block or container.
+//
+// Since: Bot API 10.1
+type RichBlockCaption struct {
+	// Text contains the formatted or plain text content.
+	Text RichText
+	// Credit contains attribution displayed with the block.
+	Credit RichText
+}
+
+// MarshalJSON implements json.Marshaler.
+//
+// Since: Bot API 10.1
+func (c RichBlockCaption) MarshalJSON() ([]byte, error) {
+	return json.Marshal(struct {
+		Text   RichText `json:"text"`
+		Credit RichText `json:"credit,omitempty"`
+	}{c.Text, c.Credit})
+}
+
+// UnmarshalJSON implements json.Unmarshaler.
+//
+// Since: Bot API 10.1
+func (c *RichBlockCaption) UnmarshalJSON(data []byte) error {
+	var raw struct {
+		Text   json.RawMessage `json:"text"`
+		Credit json.RawMessage `json:"credit"`
+	}
+	if err := json.Unmarshal(data, &raw); err != nil {
+		return err
+	}
+	text, err := parseOptRichText(raw.Text)
+	if err != nil {
+		return err
+	}
+	credit, err := parseOptRichText(raw.Credit)
+	if err != nil {
+		return err
+	}
+	*c = RichBlockCaption{text, credit}
+	return nil
+}
+
+// RichBlockListItem is a single list item. Label is the ready-to-display
+// visible marker ("1.", "c.", "vii.", "•"): the server renders it itself
+// when parsing html/markdown.
+//
+// Since: Bot API 10.1
+type RichBlockListItem struct {
+	// Label contains the list-item label.
+	Label string
+	// Blocks contains the nested rich-message blocks.
+	Blocks []RichBlock
+	// HasCheckbox reports whether the list item includes a checkbox.
+	HasCheckbox bool
+	// IsChecked reports whether the list-item checkbox is checked.
+	IsChecked bool
+	Value     int                   // for ordered lists: numeric value of the marker
+	Type      RichBlockListItemType // for ordered lists: "a", "A", "i", "I" or "1"
+}
+
+// MarshalJSON implements json.Marshaler.
+//
+// Since: Bot API 10.1
+func (i RichBlockListItem) MarshalJSON() ([]byte, error) {
+	return json.Marshal(struct {
+		Label       string                `json:"label"`
+		Blocks      []RichBlock           `json:"blocks"`
+		HasCheckbox bool                  `json:"has_checkbox,omitempty"`
+		IsChecked   bool                  `json:"is_checked,omitempty"`
+		Value       int                   `json:"value,omitempty"`
+		Type        RichBlockListItemType `json:"type,omitempty"`
+	}{i.Label, i.Blocks, i.HasCheckbox, i.IsChecked, i.Value, i.Type})
+}
+
+// UnmarshalJSON implements json.Unmarshaler.
+//
+// Since: Bot API 10.1
+func (i *RichBlockListItem) UnmarshalJSON(data []byte) error {
+	var raw struct {
+		Label       string                `json:"label"`
+		Blocks      json.RawMessage       `json:"blocks"`
+		HasCheckbox bool                  `json:"has_checkbox"`
+		IsChecked   bool                  `json:"is_checked"`
+		Value       int                   `json:"value"`
+		Type        RichBlockListItemType `json:"type"`
+	}
+	if err := json.Unmarshal(data, &raw); err != nil {
+		return err
+	}
+	blocks, err := unmarshalRichBlocks(raw.Blocks)
+	if err != nil {
+		return err
+	}
+	*i = RichBlockListItem{raw.Label, blocks, raw.HasCheckbox, raw.IsChecked, raw.Value, raw.Type}
+	return nil
+}
+
+// RichBlockTableCell is a table cell. An empty Text means an invisible cell.
+//
+// Since: Bot API 10.1
+type RichBlockTableCell struct {
+	// Text contains the formatted or plain text content.
+	Text RichText
+	// IsHeader marks the table cell as a header cell.
+	IsHeader bool
+	// ColSpan is the number of table columns spanned by the cell.
+	ColSpan int
+	// RowSpan is the number of table rows spanned by the cell.
+	RowSpan int
+	Align   string // "left", "center" or "right"
+	VAlign  string // "top", "middle" or "bottom"
+}
+
+// MarshalJSON implements json.Marshaler.
+//
+// Since: Bot API 10.1
+func (c RichBlockTableCell) MarshalJSON() ([]byte, error) {
+	return json.Marshal(struct {
+		Text     RichText `json:"text,omitempty"`
+		IsHeader bool     `json:"is_header,omitempty"`
+		Colspan  int      `json:"colspan,omitempty"`
+		Rowspan  int      `json:"rowspan,omitempty"`
+		Align    string   `json:"align,omitempty"`
+		VAlign   string   `json:"valign,omitempty"`
+	}{c.Text, c.IsHeader, c.ColSpan, c.RowSpan, c.Align, c.VAlign})
+}
+
+// UnmarshalJSON implements json.Unmarshaler.
+//
+// Since: Bot API 10.1
+func (c *RichBlockTableCell) UnmarshalJSON(data []byte) error {
+	var raw struct {
+		Text     json.RawMessage `json:"text"`
+		IsHeader bool            `json:"is_header"`
+		Colspan  int             `json:"colspan"`
+		Rowspan  int             `json:"rowspan"`
+		Align    string          `json:"align"`
+		VAlign   string          `json:"valign"`
+	}
+	if err := json.Unmarshal(data, &raw); err != nil {
+		return err
+	}
+	text, err := parseOptRichText(raw.Text)
+	if err != nil {
+		return err
+	}
+	*c = RichBlockTableCell{text, raw.IsHeader, raw.Colspan, raw.Rowspan, raw.Align, raw.VAlign}
+	return nil
+}
+
+// RichBlockWrap covers all blocks that have only a text field.
+//
+// Since: Bot API 10.1
+type RichBlockWrap struct {
+	// Tag identifies the rich-text formatting wrapper.
+	Tag string
+	// Text contains the formatted or plain text content.
+	Text RichText
+}
+
+func (RichBlockWrap) isRichBlock() {}
+
+// MarshalJSON implements json.Marshaler.
+//
+// Since: Bot API 10.1
+func (b RichBlockWrap) MarshalJSON() ([]byte, error) {
+	return json.Marshal(struct {
+		Type string   `json:"type"`
+		Text RichText `json:"text"`
+	}{b.Tag, b.Text})
+}
+
+var richBlockWrapTags = map[string]bool{
+	"paragraph": true, "footer": true, "thinking": true,
+}
+
+// RichBlockSectionHeading is a section heading block.
+//
+// Since: Bot API 10.1
+type RichBlockSectionHeading struct {
+	// Text contains the formatted or plain text content.
+	Text RichText
+	Size int // 1-6, 1 is the largest
+}
+
+func (RichBlockSectionHeading) isRichBlock() {}
+
+// MarshalJSON implements json.Marshaler.
+//
+// Since: Bot API 10.1
+func (b RichBlockSectionHeading) MarshalJSON() ([]byte, error) {
+	return json.Marshal(struct {
+		Type string   `json:"type"`
+		Text RichText `json:"text"`
+		Size int      `json:"size"`
+	}{"heading", b.Text, b.Size})
+}
+
+// RichBlockPreformatted is a preformatted code block.
+//
+// Since: Bot API 10.1
+type RichBlockPreformatted struct {
+	// Text contains the formatted or plain text content.
+	Text RichText
+	// Language identifies the programming language used for syntax highlighting.
+	Language string
+}
+
+func (RichBlockPreformatted) isRichBlock() {}
+
+// MarshalJSON implements json.Marshaler.
+//
+// Since: Bot API 10.1
+func (b RichBlockPreformatted) MarshalJSON() ([]byte, error) {
+	return json.Marshal(struct {
+		Type     string   `json:"type"`
+		Text     RichText `json:"text"`
+		Language string   `json:"language,omitempty"`
+	}{"pre", b.Text, b.Language})
+}
+
+// RichBlockQuotation is a block quotation with block-level content
+// (officially RichBlockBlockQuotation).
+//
+// Since: Bot API 10.1
+type RichBlockQuotation struct {
+	// Blocks contains the nested rich-message blocks.
+	Blocks []RichBlock
+	// Credit contains attribution displayed with the block.
+	Credit RichText
+}
+
+func (RichBlockQuotation) isRichBlock() {}
+
+// MarshalJSON implements json.Marshaler.
+//
+// Since: Bot API 10.1
+func (b RichBlockQuotation) MarshalJSON() ([]byte, error) {
+	return json.Marshal(struct {
+		Type   string      `json:"type"`
+		Blocks []RichBlock `json:"blocks"`
+		Credit RichText    `json:"credit,omitempty"`
+	}{"blockquote", b.Blocks, b.Credit})
+}
+
+// RichBlockPullQuotation is a pull quotation with inline content.
+//
+// Since: Bot API 10.1
+type RichBlockPullQuotation struct {
+	// Text contains the formatted or plain text content.
+	Text RichText
+	// Credit contains attribution displayed with the block.
+	Credit RichText
+}
+
+func (RichBlockPullQuotation) isRichBlock() {}
+
+// MarshalJSON implements json.Marshaler.
+//
+// Since: Bot API 10.1
+func (b RichBlockPullQuotation) MarshalJSON() ([]byte, error) {
+	return json.Marshal(struct {
+		Type   string   `json:"type"`
+		Text   RichText `json:"text"`
+		Credit RichText `json:"credit,omitempty"`
+	}{"pullquote", b.Text, b.Credit})
+}
+
+// RichBlockList is a list block.
+//
+// Since: Bot API 10.1
+type RichBlockList struct {
+	// Items contains the list items.
+	Items []RichBlockListItem
+}
+
+func (RichBlockList) isRichBlock() {}
+
+// MarshalJSON implements json.Marshaler.
+//
+// Since: Bot API 10.1
+func (b RichBlockList) MarshalJSON() ([]byte, error) {
+	return json.Marshal(struct {
+		Type  string              `json:"type"`
+		Items []RichBlockListItem `json:"items"`
+	}{"list", b.Items})
+}
+
+// RichBlockCollage is a collage of media blocks.
+//
+// Since: Bot API 10.1
+type RichBlockCollage struct {
+	// Blocks contains the nested rich-message blocks.
+	Blocks []RichBlock
+	// Caption contains the media or block caption.
+	Caption *RichBlockCaption
+}
+
+func (RichBlockCollage) isRichBlock() {}
+
+// MarshalJSON implements json.Marshaler.
+//
+// Since: Bot API 10.1
+func (b RichBlockCollage) MarshalJSON() ([]byte, error) {
+	return json.Marshal(struct {
+		Type    string            `json:"type"`
+		Blocks  []RichBlock       `json:"blocks"`
+		Caption *RichBlockCaption `json:"caption,omitempty"`
+	}{"collage", b.Blocks, b.Caption})
+}
+
+// RichBlockSlideshow is a slideshow of media blocks.
+//
+// Since: Bot API 10.1
+type RichBlockSlideshow struct {
+	// Blocks contains the nested rich-message blocks.
+	Blocks []RichBlock
+	// Caption contains the media or block caption.
+	Caption *RichBlockCaption
+}
+
+func (RichBlockSlideshow) isRichBlock() {}
+
+// MarshalJSON implements json.Marshaler.
+//
+// Since: Bot API 10.1
+func (b RichBlockSlideshow) MarshalJSON() ([]byte, error) {
+	return json.Marshal(struct {
+		Type    string            `json:"type"`
+		Blocks  []RichBlock       `json:"blocks"`
+		Caption *RichBlockCaption `json:"caption,omitempty"`
+	}{"slideshow", b.Blocks, b.Caption})
+}
+
+// RichBlockDetails is an expandable block with an inline summary.
+//
+// Since: Bot API 10.1
+type RichBlockDetails struct {
+	// Summary contains the visible summary of a details block.
+	Summary RichText
+	// Blocks contains the nested rich-message blocks.
+	Blocks []RichBlock
+	// IsOpen requests the details block to be expanded initially.
+	IsOpen bool
+}
+
+func (RichBlockDetails) isRichBlock() {}
+
+// MarshalJSON implements json.Marshaler.
+//
+// Since: Bot API 10.1
+func (b RichBlockDetails) MarshalJSON() ([]byte, error) {
+	return json.Marshal(struct {
+		Type    string      `json:"type"`
+		Summary RichText    `json:"summary"`
+		Blocks  []RichBlock `json:"blocks"`
+		IsOpen  bool        `json:"is_open,omitempty"`
+	}{"details", b.Summary, b.Blocks, b.IsOpen})
+}
+
+// RichBlockTable is a table block.
+//
+// Since: Bot API 10.1
+type RichBlockTable struct {
+	// Cells contains the table rows and cells.
+	Cells [][]RichBlockTableCell
+	// IsBordered requests visible table borders.
+	IsBordered bool
+	// IsStriped requests alternating table row styling.
+	IsStriped bool
+	// Caption contains the media or block caption.
+	Caption RichText
+}
+
+func (RichBlockTable) isRichBlock() {}
+
+// MarshalJSON implements json.Marshaler.
+//
+// Since: Bot API 10.1
+func (b RichBlockTable) MarshalJSON() ([]byte, error) {
+	return json.Marshal(struct {
+		Type       string                 `json:"type"`
+		Cells      [][]RichBlockTableCell `json:"cells"`
+		IsBordered bool                   `json:"is_bordered,omitempty"`
+		IsStriped  bool                   `json:"is_striped,omitempty"`
+		Caption    RichText               `json:"caption,omitempty"`
+	}{"table", b.Cells, b.IsBordered, b.IsStriped, b.Caption})
+}
+
+// RichBlockMap is a location map block.
+//
+// Since: Bot API 10.1
+type RichBlockMap struct {
+	// Location contains the map location.
+	Location Location
+	Zoom     int // 13-20
+	// Width is the requested media or map width in pixels.
+	Width int
+	// Height is the requested media or map height in pixels.
+	Height int
+	// Caption contains the media or block caption.
+	Caption *RichBlockCaption
+}
+
+func (RichBlockMap) isRichBlock() {}
+
+// MarshalJSON implements json.Marshaler.
+//
+// Since: Bot API 10.1
+func (b RichBlockMap) MarshalJSON() ([]byte, error) {
+	return json.Marshal(struct {
+		Type     string            `json:"type"`
+		Location Location          `json:"location"`
+		Zoom     int               `json:"zoom"`
+		Width    int               `json:"width"`
+		Height   int               `json:"height"`
+		Caption  *RichBlockCaption `json:"caption,omitempty"`
+	}{"map", b.Location, b.Zoom, b.Width, b.Height, b.Caption})
+}
+
+// RichBlockPhoto is a photo block.
+//
+// Since: Bot API 10.1
+type RichBlockPhoto struct {
+	// Photo contains or identifies the associated photo.
+	Photo []PhotoSize
+	// HasSpoiler reports whether the media is covered by a spoiler.
+	HasSpoiler bool
+	// Caption contains the media or block caption.
+	Caption *RichBlockCaption
+}
+
+func (RichBlockPhoto) isRichBlock() {}
+
+// MarshalJSON implements json.Marshaler.
+//
+// Since: Bot API 10.1
+func (b RichBlockPhoto) MarshalJSON() ([]byte, error) {
+	return json.Marshal(struct {
+		Type       string            `json:"type"`
+		Photo      []PhotoSize       `json:"photo"`
+		HasSpoiler bool              `json:"has_spoiler,omitempty"`
+		Caption    *RichBlockCaption `json:"caption,omitempty"`
+	}{"photo", b.Photo, b.HasSpoiler, b.Caption})
+}
+
+// RichBlockVideo is a video block.
+//
+// Since: Bot API 10.1
+type RichBlockVideo struct {
+	// Video contains the video rendered by the block.
+	Video Video
+	// HasSpoiler reports whether the media is covered by a spoiler.
+	HasSpoiler bool
+	// Caption contains the media or block caption.
+	Caption *RichBlockCaption
+}
+
+func (RichBlockVideo) isRichBlock() {}
+
+// MarshalJSON implements json.Marshaler.
+//
+// Since: Bot API 10.1
+func (b RichBlockVideo) MarshalJSON() ([]byte, error) {
+	return json.Marshal(struct {
+		Type       string            `json:"type"`
+		Video      Video             `json:"video"`
+		HasSpoiler bool              `json:"has_spoiler,omitempty"`
+		Caption    *RichBlockCaption `json:"caption,omitempty"`
+	}{"video", b.Video, b.HasSpoiler, b.Caption})
+}
+
+// RichBlockAudio is an audio block.
+//
+// Since: Bot API 10.1
+type RichBlockAudio struct {
+	// Audio contains the audio rendered by the block.
+	Audio Audio
+	// Caption contains the media or block caption.
+	Caption *RichBlockCaption
+}
+
+func (RichBlockAudio) isRichBlock() {}
+
+// MarshalJSON implements json.Marshaler.
+//
+// Since: Bot API 10.1
+func (b RichBlockAudio) MarshalJSON() ([]byte, error) {
+	return json.Marshal(struct {
+		Type    string            `json:"type"`
+		Audio   Audio             `json:"audio"`
+		Caption *RichBlockCaption `json:"caption,omitempty"`
+	}{"audio", b.Audio, b.Caption})
+}
+
+// RichBlockAnimation is an animation block.
+//
+// Since: Bot API 10.1
+type RichBlockAnimation struct {
+	// Animation contains the animation rendered by the block.
+	Animation Animation
+	// HasSpoiler reports whether the media is covered by a spoiler.
+	HasSpoiler bool
+	// Caption contains the media or block caption.
+	Caption *RichBlockCaption
+}
+
+func (RichBlockAnimation) isRichBlock() {}
+
+// MarshalJSON implements json.Marshaler.
+//
+// Since: Bot API 10.1
+func (b RichBlockAnimation) MarshalJSON() ([]byte, error) {
+	return json.Marshal(struct {
+		Type       string            `json:"type"`
+		Animation  Animation         `json:"animation"`
+		HasSpoiler bool              `json:"has_spoiler,omitempty"`
+		Caption    *RichBlockCaption `json:"caption,omitempty"`
+	}{"animation", b.Animation, b.HasSpoiler, b.Caption})
+}
+
+// RichBlockVoiceNote is a voice note block.
+//
+// Since: Bot API 10.1
+type RichBlockVoiceNote struct {
+	// VoiceNote contains the voice note rendered by the block.
+	VoiceNote Voice
+	// Caption contains the media or block caption.
+	Caption *RichBlockCaption
+}
+
+func (RichBlockVoiceNote) isRichBlock() {}
+
+// MarshalJSON implements json.Marshaler.
+//
+// Since: Bot API 10.1
+func (b RichBlockVoiceNote) MarshalJSON() ([]byte, error) {
+	return json.Marshal(struct {
+		Type      string            `json:"type"`
+		VoiceNote Voice             `json:"voice_note"`
+		Caption   *RichBlockCaption `json:"caption,omitempty"`
+	}{"voice_note", b.VoiceNote, b.Caption})
+}
+
+// RichBlockDivider is a horizontal divider block.
+//
+// Since: Bot API 10.1
+type RichBlockDivider struct{}
+
+func (RichBlockDivider) isRichBlock() {}
+
+// MarshalJSON implements json.Marshaler.
+//
+// Since: Bot API 10.1
+func (b RichBlockDivider) MarshalJSON() ([]byte, error) {
+	return json.Marshal(struct {
+		Type string `json:"type"`
+	}{"divider"})
+}
+
+// RichBlockMathematicalExpression is a block-level mathematical expression.
+//
+// Since: Bot API 10.1
+type RichBlockMathematicalExpression struct {
+	// Expression contains the mathematical expression source.
+	Expression string
+}
+
+func (RichBlockMathematicalExpression) isRichBlock() {}
+
+// MarshalJSON implements json.Marshaler.
+//
+// Since: Bot API 10.1
+func (b RichBlockMathematicalExpression) MarshalJSON() ([]byte, error) {
+	return json.Marshal(struct {
+		Type       string `json:"type"`
+		Expression string `json:"expression"`
+	}{"mathematical_expression", b.Expression})
+}
+
+// RichBlockAnchor is a named anchor block that anchor links can point to.
+//
+// Since: Bot API 10.1
+type RichBlockAnchor struct {
+	// Name is the user-facing or reference name of the value.
+	Name string
+}
+
+func (RichBlockAnchor) isRichBlock() {}
+
+// MarshalJSON implements json.Marshaler.
+//
+// Since: Bot API 10.1
+func (b RichBlockAnchor) MarshalJSON() ([]byte, error) {
+	return json.Marshal(struct {
+		Type string `json:"type"`
+		Name string `json:"name"`
+	}{"anchor", b.Name})
+}

tgapi/rich_input_types.go

@@ -0,0 +1,427 @@
+package tgapi
+
+// InputRichType identifies the JSON type of an input rich block.
+//
+// Since: Bot API 10.2
+type InputRichType string
+
+const (
+	// InputRichTypeParagraph identifies a paragraph block.
+	InputRichTypeParagraph InputRichType = "paragraph"
+	// InputRichTypeSectionHeading identifies a section-heading block.
+	InputRichTypeSectionHeading InputRichType = "heading"
+	// InputRichTypePre identifies a preformatted block.
+	InputRichTypePre InputRichType = "pre"
+	// InputRichTypeFooter identifies a footer block.
+	InputRichTypeFooter InputRichType = "footer"
+	// InputRichTypeDivider identifies a divider block.
+	InputRichTypeDivider InputRichType = "divider"
+	// InputRichTypeMathematicalExpression identifies a mathematical-expression block.
+	InputRichTypeMathematicalExpression InputRichType = "mathematical_expression"
+	// InputRichTypeAnchor identifies an anchor block.
+	InputRichTypeAnchor InputRichType = "anchor"
+	// InputRichTypeList identifies a list block.
+	InputRichTypeList InputRichType = "list"
+	// InputRichTypeBlockQuotation identifies a block-quotation block.
+	InputRichTypeBlockQuotation InputRichType = "blockquote"
+	// InputRichTypePullQuotation identifies a pull-quotation block.
+	InputRichTypePullQuotation InputRichType = "pullquote"
+	// InputRichTypeCollage identifies a collage block.
+	InputRichTypeCollage InputRichType = "collage"
+	// InputRichTypeSlideshow identifies a slideshow block.
+	InputRichTypeSlideshow InputRichType = "slideshow"
+	// InputRichTypeTable identifies a table block.
+	InputRichTypeTable InputRichType = "table"
+	// InputRichTypeDetails identifies an expandable details block.
+	InputRichTypeDetails InputRichType = "details"
+	// InputRichTypeMap identifies a map block.
+	InputRichTypeMap InputRichType = "map"
+	// InputRichTypeAnimation identifies an animation block.
+	InputRichTypeAnimation InputRichType = "animation"
+	// InputRichTypeAudio identifies an audio block.
+	InputRichTypeAudio InputRichType = "audio"
+	// InputRichTypePhoto identifies a photo block.
+	InputRichTypePhoto InputRichType = "photo"
+	// InputRichTypeVideo identifies a video block.
+	InputRichTypeVideo InputRichType = "video"
+	// InputRichTypeVoiceNote identifies a voice-note block.
+	InputRichTypeVoiceNote InputRichType = "voice_note"
+	// InputRichTypeThinking identifies a thinking block.
+	InputRichTypeThinking InputRichType = "thinking"
+)
+
+// InputRichBlock represents a block available to format an outgoing rich message.
+//
+// Since: Bot API 10.2
+type InputRichBlock interface {
+	isInputRichBlock()
+}
+
+// InputRichBlockParagraph is a text paragraph corresponding to the HTML <p> tag.
+//
+// Since: Bot API 10.2
+type InputRichBlockParagraph struct {
+	// Type is the Bot API type discriminator.
+	Type InputRichType `json:"type"`
+	// Text contains the formatted or plain text content.
+	Text RichText `json:"text"`
+}
+
+func (InputRichBlockParagraph) isInputRichBlock() {}
+
+// InputRichBlockSectionHeading is a section heading corresponding to an HTML <h1> through <h6> tag.
+//
+// Since: Bot API 10.2
+type InputRichBlockSectionHeading struct {
+	// Type is the Bot API type discriminator.
+	Type InputRichType `json:"type"`
+	// Text contains the formatted or plain text content.
+	Text RichText `json:"text"`
+	// Size selects the section heading level from 1 through 6.
+	Size uint8 `json:"size"`
+}
+
+func (InputRichBlockSectionHeading) isInputRichBlock() {}
+
+// InputRichBlockPreformatted is a preformatted text block corresponding to nested HTML <pre> and <code> tags.
+//
+// Since: Bot API 10.2
+type InputRichBlockPreformatted struct {
+	// Type is the Bot API type discriminator.
+	Type InputRichType `json:"type"`
+	// Text contains the formatted or plain text content.
+	Text RichText `json:"text"`
+	// Language identifies the programming language used for syntax highlighting.
+	Language string `json:"language,omitempty"`
+}
+
+func (InputRichBlockPreformatted) isInputRichBlock() {}
+
+// InputRichBlockFooter is a footer corresponding to the HTML <footer> tag.
+//
+// Since: Bot API 10.2
+type InputRichBlockFooter struct {
+	// Type is the Bot API type discriminator.
+	Type InputRichType `json:"type"`
+	// Text contains the formatted or plain text content.
+	Text RichText `json:"text"`
+}
+
+func (InputRichBlockFooter) isInputRichBlock() {}
+
+// InputRichBlockDivider is a divider corresponding to the HTML <hr/> tag.
+//
+// Since: Bot API 10.2
+type InputRichBlockDivider struct {
+	// Type is the Bot API type discriminator.
+	Type InputRichType `json:"type"`
+}
+
+func (InputRichBlockDivider) isInputRichBlock() {}
+
+// InputRichBlockMath is a block containing a mathematical expression in LaTeX format,
+// corresponding to the custom HTML <tg-math-block> tag.
+//
+// Since: Bot API 10.2
+type InputRichBlockMath struct {
+	// Type is the Bot API type discriminator.
+	Type InputRichType `json:"type"`
+	// Expression contains the mathematical expression source.
+	Expression string `json:"expression"`
+}
+
+func (InputRichBlockMath) isInputRichBlock() {}
+
+// InputRichBlockAnchor is a block containing an anchor corresponding to an HTML <a> tag with a name attribute.
+//
+// Since: Bot API 10.2
+type InputRichBlockAnchor struct {
+	// Type is the Bot API type discriminator.
+	Type InputRichType `json:"type"`
+	// Name is the user-facing or reference name of the value.
+	Name string `json:"name"`
+}
+
+func (InputRichBlockAnchor) isInputRichBlock() {}
+
+// RichBlockListItemType identifies an ordered-list label style.
+//
+// Since: Bot API 10.2
+type RichBlockListItemType string
+
+const (
+	// InputRichBlockListItemTypeLower uses lowercase letters.
+	InputRichBlockListItemTypeLower RichBlockListItemType = "a"
+	// InputRichBlockListItemTypeUpper uses uppercase letters.
+	InputRichBlockListItemTypeUpper RichBlockListItemType = "A"
+	// InputRichBlockListItemTypeRomanLow uses lowercase Roman numerals.
+	InputRichBlockListItemTypeRomanLow RichBlockListItemType = "i"
+	// InputRichBlockListItemTypeRomanUpper uses uppercase Roman numerals.
+	InputRichBlockListItemTypeRomanUpper RichBlockListItemType = "I"
+	// InputRichBlockListItemTypeDecimal uses decimal numbers.
+	InputRichBlockListItemTypeDecimal RichBlockListItemType = "1"
+)
+
+// InputRichBlockListItem represents an item in an input rich-message list.
+//
+// Since: Bot API 10.2
+type InputRichBlockListItem struct {
+	// Blocks contains the nested rich-message blocks.
+	Blocks []InputRichBlock `json:"blocks"`
+	// HasCheckbox reports whether the list item includes a checkbox.
+	HasCheckbox bool `json:"has_checkbox,omitempty"`
+	// IsChecked reports whether the list-item checkbox is checked.
+	IsChecked bool `json:"is_checked,omitempty"`
+	// Value sets the numeric marker value for an ordered list item.
+	Value int `json:"value,omitempty"`
+	// Type is the Bot API type discriminator.
+	Type RichBlockListItemType `json:"type,omitempty"`
+}
+
+// NewInputRichBlockListItem creates a list item containing blocks.
+//
+// Since: Bot API 10.2
+func NewInputRichBlockListItem(blocks ...InputRichBlock) *InputRichBlockListItem {
+	return &InputRichBlockListItem{Blocks: blocks}
+}
+
+// SetCheckbox configures whether the list item has a checkbox.
+//
+// Since: Bot API 10.2
+func (i *InputRichBlockListItem) SetCheckbox(hasCheckbox bool) *InputRichBlockListItem {
+	i.HasCheckbox = hasCheckbox
+	return i
+}
+
+// Check marks the list item's checkbox as checked.
+//
+// Since: Bot API 10.2
+func (i *InputRichBlockListItem) Check() *InputRichBlockListItem {
+	i.IsChecked = true
+	return i
+}
+
+// SetValue sets the numeric value of an ordered-list item.
+//
+// Since: Bot API 10.2
+func (i *InputRichBlockListItem) SetValue(val int) *InputRichBlockListItem {
+	i.Value = val
+	return i
+}
+
+// SetType sets the label style of an ordered-list item.
+//
+// Since: Bot API 10.2
+func (i *InputRichBlockListItem) SetType(t RichBlockListItemType) *InputRichBlockListItem {
+	i.Type = t
+	return i
+}
+
+// InputRichBlockList is a list of input rich-message blocks.
+//
+// Since: Bot API 10.2
+type InputRichBlockList struct {
+	// Type is the Bot API type discriminator.
+	Type InputRichType `json:"type"`
+	// Items contains the list items.
+	Items []InputRichBlockListItem `json:"items"`
+}
+
+func (InputRichBlockList) isInputRichBlock() {}
+
+// InputRichBlockBlockQuotation is a block quotation in an input rich message.
+//
+// Since: Bot API 10.2
+type InputRichBlockBlockQuotation struct {
+	// Type is the Bot API type discriminator.
+	Type InputRichType `json:"type"`
+	// Blocks contains the nested rich-message blocks.
+	Blocks []InputRichBlock `json:"blocks"`
+	// Credit contains attribution displayed with the block.
+	Credit *RichText `json:"credit,omitempty"`
+}
+
+func (InputRichBlockBlockQuotation) isInputRichBlock() {}
+
+// InputRichBlockPullQuotation is a centered quotation in an input rich message.
+//
+// Since: Bot API 10.2
+type InputRichBlockPullQuotation struct {
+	// Type is the Bot API type discriminator.
+	Type InputRichType `json:"type"`
+	// Text contains the formatted or plain text content.
+	Text RichText `json:"text"`
+	// Credit contains attribution displayed with the block.
+	Credit *RichText `json:"credit,omitempty"`
+}
+
+func (InputRichBlockPullQuotation) isInputRichBlock() {}
+
+// InputRichBlockCollage is a collage in an input rich message.
+//
+// Since: Bot API 10.2
+type InputRichBlockCollage struct {
+	// Type is the Bot API type discriminator.
+	Type InputRichType `json:"type"`
+	// Blocks contains the nested rich-message blocks.
+	Blocks []InputRichBlock `json:"blocks"`
+	// Caption contains the media or block caption.
+	Caption *RichBlockCaption `json:"caption,omitempty"`
+}
+
+func (InputRichBlockCollage) isInputRichBlock() {}
+
+// InputRichBlockSlideshow is a slideshow in an input rich message.
+//
+// Since: Bot API 10.2
+type InputRichBlockSlideshow struct {
+	// Type is the Bot API type discriminator.
+	Type InputRichType `json:"type"`
+	// Blocks contains the nested rich-message blocks.
+	Blocks []InputRichBlock `json:"blocks"`
+	// Caption contains the media or block caption.
+	Caption *RichBlockCaption `json:"caption,omitempty"`
+}
+
+func (InputRichBlockSlideshow) isInputRichBlock() {}
+
+// InputRichBlockTable is a table in an input rich message.
+//
+// Since: Bot API 10.2
+type InputRichBlockTable struct {
+	// Type is the Bot API type discriminator.
+	Type InputRichType `json:"type"`
+	// Cells contains the table rows and cells.
+	Cells [][]RichBlockTableCell `json:"cells"`
+	// IsBordered requests visible table borders.
+	IsBordered bool `json:"is_bordered,omitempty"`
+	// IsStriped requests alternating table row styling.
+	IsStriped bool `json:"is_striped,omitempty"`
+	// Caption contains the media or block caption.
+	Caption *RichText `json:"caption,omitempty"`
+}
+
+func (InputRichBlockTable) isInputRichBlock() {}
+
+// InputRichBlockDetails is an expandable block in an input rich message.
+//
+// Since: Bot API 10.2
+type InputRichBlockDetails struct {
+	// Type is the Bot API type discriminator.
+	Type InputRichType `json:"type"`
+	// Summary contains the visible summary of a details block.
+	Summary RichText `json:"summary"`
+	// Blocks contains the nested rich-message blocks.
+	Blocks []InputRichBlock `json:"blocks"`
+	// IsOpen requests the details block to be expanded initially.
+	IsOpen bool `json:"is_open,omitempty"`
+}
+
+func (InputRichBlockDetails) isInputRichBlock() {}
+
+// InputRichBlockMap is a location map in an input rich message.
+//
+// Since: Bot API 10.2
+type InputRichBlockMap struct {
+	// Type is the Bot API type discriminator.
+	Type InputRichType `json:"type"`
+	// Location contains the map location.
+	Location Location `json:"location"`
+	// Zoom sets the map zoom level.
+	Zoom uint8 `json:"zoom,omitempty"`
+	// Width is the requested media or map width in pixels.
+	Width uint16 `json:"width,omitempty"`
+	// Height is the requested media or map height in pixels.
+	Height uint16 `json:"height,omitempty"`
+	// Caption contains the media or block caption.
+	Caption *RichBlockCaption `json:"caption,omitempty"`
+}
+
+func (InputRichBlockMap) isInputRichBlock() {}
+
+// InputRichBlockAnimation is an animation block corresponding to the HTML <video> tag.
+// The animation caption is ignored; use Caption instead.
+//
+// Since: Bot API 10.2
+type InputRichBlockAnimation struct {
+	// Type is the Bot API type discriminator.
+	Type InputRichType `json:"type"`
+	// Animation contains the animation rendered by the block.
+	Animation InputMedia `json:"animation"`
+	// Caption contains the media or block caption.
+	Caption *RichBlockCaption `json:"caption,omitempty"`
+}
+
+func (InputRichBlockAnimation) isInputRichBlock() {}
+
+// InputRichBlockAudio is a music-file block corresponding to the HTML <audio> tag.
+// The audio caption is ignored; use Caption instead.
+//
+// Since: Bot API 10.2
+type InputRichBlockAudio struct {
+	// Type is the Bot API type discriminator.
+	Type InputRichType `json:"type"`
+	// Audio contains the audio rendered by the block.
+	Audio InputMedia `json:"audio"`
+	// Caption contains the media or block caption.
+	Caption *RichBlockCaption `json:"caption,omitempty"`
+}
+
+func (InputRichBlockAudio) isInputRichBlock() {}
+
+// InputRichBlockPhoto is a photo block corresponding to the HTML <img> tag.
+// The photo caption is ignored; use Caption instead.
+//
+// Since: Bot API 10.2
+type InputRichBlockPhoto struct {
+	// Type is the Bot API type discriminator.
+	Type InputRichType `json:"type"`
+	// Photo contains or identifies the associated photo.
+	Photo InputMedia `json:"photo"`
+	// Caption contains the media or block caption.
+	Caption *RichBlockCaption `json:"caption,omitempty"`
+}
+
+func (InputRichBlockPhoto) isInputRichBlock() {}
+
+// InputRichBlockVideo is a video block corresponding to the HTML <video> tag.
+// The video caption is ignored; use Caption instead.
+//
+// Since: Bot API 10.2
+type InputRichBlockVideo struct {
+	// Type is the Bot API type discriminator.
+	Type InputRichType `json:"type"`
+	// Video contains the video rendered by the block.
+	Video InputMedia `json:"video"`
+	// Caption contains the media or block caption.
+	Caption *RichBlockCaption `json:"caption,omitempty"`
+}
+
+func (InputRichBlockVideo) isInputRichBlock() {}
+
+// InputRichBlockVoiceNote is a voice-note block corresponding to the HTML <audio> tag.
+// The voice-note caption is ignored; use Caption instead.
+//
+// Since: Bot API 10.2
+type InputRichBlockVoiceNote struct {
+	// Type is the Bot API type discriminator.
+	Type InputRichType `json:"type"`
+	// VoiceNote contains the voice note rendered by the block.
+	VoiceNote InputMedia `json:"voice_note"`
+	// Caption contains the media or block caption.
+	Caption *RichBlockCaption `json:"caption,omitempty"`
+}
+
+func (InputRichBlockVoiceNote) isInputRichBlock() {}
+
+// InputRichBlockThinking is a block for displaying a thinking state.
+//
+// Since: Bot API 10.2
+type InputRichBlockThinking struct {
+	// Type is the Bot API type discriminator.
+	Type InputRichType `json:"type"`
+	// Text contains the formatted or plain text content.
+	Text RichText `json:"text"`
+}
+
+func (InputRichBlockThinking) isInputRichBlock() {}

tgapi/rich_input_types_test.go

@@ -0,0 +1,65 @@
+package tgapi
+
+import (
+	"encoding/json"
+	"testing"
+)
+
+func TestInputRichMediaBlocksMarshal(t *testing.T) {
+	caption := RichBlockCaption{Text: RichTextPlain("caption")}
+	cases := []struct {
+		name      string
+		block     InputRichBlock
+		blockType InputRichType
+		mediaKey  string
+		mediaType InputMediaType
+	}{
+		{"animation", InputRichBlockAnimation{Type: InputRichTypeAnimation, Animation: InputMedia{Type: InputMediaTypeAnimation, Media: "animation-id"}, Caption: &caption}, InputRichTypeAnimation, "animation", InputMediaTypeAnimation},
+		{"audio", InputRichBlockAudio{Type: InputRichTypeAudio, Audio: InputMedia{Type: InputMediaTypeAudio, Media: "audio-id"}, Caption: &caption}, InputRichTypeAudio, "audio", InputMediaTypeAudio},
+		{"photo", InputRichBlockPhoto{Type: InputRichTypePhoto, Photo: InputMedia{Type: InputMediaTypePhoto, Media: "photo-id"}, Caption: &caption}, InputRichTypePhoto, "photo", InputMediaTypePhoto},
+		{"video", InputRichBlockVideo{Type: InputRichTypeVideo, Video: InputMedia{Type: InputMediaTypeVideo, Media: "video-id"}, Caption: &caption}, InputRichTypeVideo, "video", InputMediaTypeVideo},
+		{"voice note", InputRichBlockVoiceNote{Type: InputRichTypeVoiceNote, VoiceNote: InputMedia{Type: InputMediaTypeVoiceNote, Media: "voice-id"}, Caption: &caption}, InputRichTypeVoiceNote, "voice_note", InputMediaTypeVoiceNote},
+	}
+
+	for _, tt := range cases {
+		t.Run(tt.name, func(t *testing.T) {
+			data, err := json.Marshal(InputRichMessage{Blocks: []InputRichBlock{tt.block}})
+			if err != nil {
+				t.Fatalf("Marshal returned error: %v", err)
+			}
+
+			var message struct {
+				Blocks []map[string]json.RawMessage `json:"blocks"`
+			}
+			if err := json.Unmarshal(data, &message); err != nil {
+				t.Fatalf("Unmarshal returned error: %v", err)
+			}
+			if len(message.Blocks) != 1 {
+				t.Fatalf("got %d blocks, want 1", len(message.Blocks))
+			}
+
+			var blockType InputRichType
+			if err := json.Unmarshal(message.Blocks[0]["type"], &blockType); err != nil {
+				t.Fatalf("unmarshal block type: %v", err)
+			}
+			if blockType != tt.blockType {
+				t.Errorf("block type = %q, want %q", blockType, tt.blockType)
+			}
+
+			var media InputMedia
+			if err := json.Unmarshal(message.Blocks[0][tt.mediaKey], &media); err != nil {
+				t.Fatalf("unmarshal %s: %v", tt.mediaKey, err)
+			}
+			if media.Type != tt.mediaType {
+				t.Errorf("media type = %q, want %q", media.Type, tt.mediaType)
+			}
+			if message.Blocks[0]["caption"] == nil {
+				t.Error("caption is missing")
+			}
+		})
+	}
+}
+
+func TestInputRichBlockMapImplementsInputRichBlock(t *testing.T) {
+	var _ InputRichBlock = InputRichBlockMap{}
+}

tgapi/rich_text_types.go

@@ -0,0 +1,418 @@
+package tgapi
+
+import "encoding/json"
+
+// RichText is a node of the rich formatted text tree: a plain string, an
+// array, or one of the typed objects below.
+//
+// Since: Bot API 10.1
+type RichText interface {
+	isRichText()
+}
+
+// RichTextPlain is a plain text leaf.
+//
+// Since: Bot API 10.1
+type RichTextPlain string
+
+func (RichTextPlain) isRichText() {}
+
+// RichTextArray is a concatenation of rich text nodes.
+//
+// Since: Bot API 10.1
+type RichTextArray []RichText
+
+func (RichTextArray) isRichText() {}
+
+// RichTextWrap covers all "pure" wrapper nodes with a single type.
+//
+// Since: Bot API 10.1
+type RichTextWrap struct {
+	// Tag identifies the rich-text formatting wrapper.
+	Tag string
+	// Text contains the formatted or plain text content.
+	Text RichText
+}
+
+func (RichTextWrap) isRichText() {}
+
+// MarshalJSON implements json.Marshaler.
+//
+// Since: Bot API 10.1
+func (w RichTextWrap) MarshalJSON() ([]byte, error) {
+	return json.Marshal(struct {
+		Type string   `json:"type"`
+		Text RichText `json:"text"`
+	}{w.Tag, w.Text})
+}
+
+var richTextWrapTags = map[string]bool{
+	"bold": true, "italic": true, "underline": true,
+	"strikethrough": true, "spoiler": true, "subscript": true,
+	"superscript": true, "marked": true, "code": true,
+}
+
+// RichTextURL is rich text linking to a URL.
+//
+// Since: Bot API 10.1
+type RichTextURL struct {
+	// Text contains the formatted or plain text content.
+	Text RichText
+	// URL contains the HTTP URL.
+	URL string
+}
+
+func (RichTextURL) isRichText() {}
+
+// MarshalJSON implements json.Marshaler.
+//
+// Since: Bot API 10.1
+func (v RichTextURL) MarshalJSON() ([]byte, error) {
+	return json.Marshal(struct {
+		Type string   `json:"type"`
+		Text RichText `json:"text"`
+		URL  string   `json:"url"`
+	}{"url", v.Text, v.URL})
+}
+
+// RichTextEmailAddress is rich text linking to an email address.
+//
+// Since: Bot API 10.1
+type RichTextEmailAddress struct {
+	// Text contains the formatted or plain text content.
+	Text RichText
+	// EmailAddress is the email address associated with the text.
+	EmailAddress string
+}
+
+func (RichTextEmailAddress) isRichText() {}
+
+// MarshalJSON implements json.Marshaler.
+//
+// Since: Bot API 10.1
+func (v RichTextEmailAddress) MarshalJSON() ([]byte, error) {
+	return json.Marshal(struct {
+		Type         string   `json:"type"`
+		Text         RichText `json:"text"`
+		EmailAddress string   `json:"email_address"`
+	}{"email_address", v.Text, v.EmailAddress})
+}
+
+// RichTextPhoneNumber is rich text linking to a phone number.
+//
+// Since: Bot API 10.1
+type RichTextPhoneNumber struct {
+	// Text contains the formatted or plain text content.
+	Text RichText
+	// PhoneNumber is the phone number associated with the text.
+	PhoneNumber string
+}
+
+func (RichTextPhoneNumber) isRichText() {}
+
+// MarshalJSON implements json.Marshaler.
+//
+// Since: Bot API 10.1
+func (v RichTextPhoneNumber) MarshalJSON() ([]byte, error) {
+	return json.Marshal(struct {
+		Type        string   `json:"type"`
+		Text        RichText `json:"text"`
+		PhoneNumber string   `json:"phone_number"`
+	}{"phone_number", v.Text, v.PhoneNumber})
+}
+
+// RichTextBankCardNumber is rich text marked as a bank card number.
+//
+// Since: Bot API 10.1
+type RichTextBankCardNumber struct {
+	// Text contains the formatted or plain text content.
+	Text RichText
+	// BankCardNumber is the bank card number associated with the text.
+	BankCardNumber string
+}
+
+func (RichTextBankCardNumber) isRichText() {}
+
+// MarshalJSON implements json.Marshaler.
+//
+// Since: Bot API 10.1
+func (v RichTextBankCardNumber) MarshalJSON() ([]byte, error) {
+	return json.Marshal(struct {
+		Type           string   `json:"type"`
+		Text           RichText `json:"text"`
+		BankCardNumber string   `json:"bank_card_number"`
+	}{"bank_card_number", v.Text, v.BankCardNumber})
+}
+
+// RichTextMention is rich text mentioning a user by username.
+//
+// Since: Bot API 10.1
+type RichTextMention struct {
+	// Text contains the formatted or plain text content.
+	Text RichText
+	// Username is the username associated with the mention.
+	Username string
+}
+
+func (RichTextMention) isRichText() {}
+
+// MarshalJSON implements json.Marshaler.
+//
+// Since: Bot API 10.1
+func (v RichTextMention) MarshalJSON() ([]byte, error) {
+	return json.Marshal(struct {
+		Type     string   `json:"type"`
+		Text     RichText `json:"text"`
+		Username string   `json:"username"`
+	}{"mention", v.Text, v.Username})
+}
+
+// RichTextHashtag is rich text marked as a hashtag.
+//
+// Since: Bot API 10.1
+type RichTextHashtag struct {
+	// Text contains the formatted or plain text content.
+	Text RichText
+	// Hashtag is the hashtag associated with the text.
+	Hashtag string
+}
+
+func (RichTextHashtag) isRichText() {}
+
+// MarshalJSON implements json.Marshaler.
+//
+// Since: Bot API 10.1
+func (v RichTextHashtag) MarshalJSON() ([]byte, error) {
+	return json.Marshal(struct {
+		Type    string   `json:"type"`
+		Text    RichText `json:"text"`
+		Hashtag string   `json:"hashtag"`
+	}{"hashtag", v.Text, v.Hashtag})
+}
+
+// RichTextCashtag is rich text marked as a cashtag.
+//
+// Since: Bot API 10.1
+type RichTextCashtag struct {
+	// Text contains the formatted or plain text content.
+	Text RichText
+	// Cashtag is the cashtag associated with the text.
+	Cashtag string
+}
+
+func (RichTextCashtag) isRichText() {}
+
+// MarshalJSON implements json.Marshaler.
+//
+// Since: Bot API 10.1
+func (v RichTextCashtag) MarshalJSON() ([]byte, error) {
+	return json.Marshal(struct {
+		Type    string   `json:"type"`
+		Text    RichText `json:"text"`
+		Cashtag string   `json:"cashtag"`
+	}{"cashtag", v.Text, v.Cashtag})
+}
+
+// RichTextBotCommand is rich text marked as a bot command.
+//
+// Since: Bot API 10.1
+type RichTextBotCommand struct {
+	// Text contains the formatted or plain text content.
+	Text RichText
+	// BotCommand is the bot command associated with the text.
+	BotCommand string
+}
+
+func (RichTextBotCommand) isRichText() {}
+
+// MarshalJSON implements json.Marshaler.
+//
+// Since: Bot API 10.1
+func (v RichTextBotCommand) MarshalJSON() ([]byte, error) {
+	return json.Marshal(struct {
+		Type       string   `json:"type"`
+		Text       RichText `json:"text"`
+		BotCommand string   `json:"bot_command"`
+	}{"bot_command", v.Text, v.BotCommand})
+}
+
+// RichTextAnchorLink is rich text linking to a named anchor in the same message.
+//
+// Since: Bot API 10.1
+type RichTextAnchorLink struct {
+	// Text contains the formatted or plain text content.
+	Text RichText
+	// AnchorName names the anchor targeted by the link.
+	AnchorName string
+}
+
+func (RichTextAnchorLink) isRichText() {}
+
+// MarshalJSON implements json.Marshaler.
+//
+// Since: Bot API 10.1
+func (v RichTextAnchorLink) MarshalJSON() ([]byte, error) {
+	return json.Marshal(struct {
+		Type       string   `json:"type"`
+		Text       RichText `json:"text"`
+		AnchorName string   `json:"anchor_name"`
+	}{"anchor_link", v.Text, v.AnchorName})
+}
+
+// RichTextReference is rich text marked as a named reference target.
+//
+// Since: Bot API 10.1
+type RichTextReference struct {
+	// Text contains the formatted or plain text content.
+	Text RichText
+	// Name is the user-facing or reference name of the value.
+	Name string
+}
+
+func (RichTextReference) isRichText() {}
+
+// MarshalJSON implements json.Marshaler.
+//
+// Since: Bot API 10.1
+func (v RichTextReference) MarshalJSON() ([]byte, error) {
+	return json.Marshal(struct {
+		Type string   `json:"type"`
+		Text RichText `json:"text"`
+		Name string   `json:"name"`
+	}{"reference", v.Text, v.Name})
+}
+
+// RichTextReferenceLink is rich text linking to a named reference.
+//
+// Since: Bot API 10.1
+type RichTextReferenceLink struct {
+	// Text contains the formatted or plain text content.
+	Text RichText
+	// ReferenceName names the reference targeted by the link.
+	ReferenceName string
+}
+
+func (RichTextReferenceLink) isRichText() {}
+
+// MarshalJSON implements json.Marshaler.
+//
+// Since: Bot API 10.1
+func (v RichTextReferenceLink) MarshalJSON() ([]byte, error) {
+	return json.Marshal(struct {
+		Type          string   `json:"type"`
+		Text          RichText `json:"text"`
+		ReferenceName string   `json:"reference_name"`
+	}{"reference_link", v.Text, v.ReferenceName})
+}
+
+// RichTextDateTime is rich text bound to a point in time with a display format.
+//
+// Since: Bot API 10.1
+type RichTextDateTime struct {
+	// Text contains the formatted or plain text content.
+	Text RichText
+	// UnixTime is the Unix timestamp associated with the text.
+	UnixTime int64
+	// DateTimeFormat controls how the associated Unix time is displayed.
+	DateTimeFormat string
+}
+
+func (RichTextDateTime) isRichText() {}
+
+// MarshalJSON implements json.Marshaler.
+//
+// Since: Bot API 10.1
+func (v RichTextDateTime) MarshalJSON() ([]byte, error) {
+	return json.Marshal(struct {
+		Type           string   `json:"type"`
+		Text           RichText `json:"text"`
+		UnixTime       int64    `json:"unix_time"`
+		DateTimeFormat string   `json:"date_time_format"`
+	}{"date_time", v.Text, v.UnixTime, v.DateTimeFormat})
+}
+
+// RichTextTextMention is rich text mentioning a user without a username.
+//
+// Since: Bot API 10.1
+type RichTextTextMention struct {
+	// Text contains the formatted or plain text content.
+	Text RichText
+	// User contains the user associated with the value.
+	User User
+}
+
+func (RichTextTextMention) isRichText() {}
+
+// MarshalJSON implements json.Marshaler.
+//
+// Since: Bot API 10.1
+func (v RichTextTextMention) MarshalJSON() ([]byte, error) {
+	return json.Marshal(struct {
+		Type string   `json:"type"`
+		Text RichText `json:"text"`
+		User User     `json:"user"`
+	}{"text_mention", v.Text, v.User})
+}
+
+// RichTextCustomEmoji is a custom emoji leaf with alternative text.
+//
+// Since: Bot API 10.1
+type RichTextCustomEmoji struct {
+	// CustomEmojiID identifies the custom emoji.
+	CustomEmojiID string
+	// AlternativeText is shown when the custom emoji can't be rendered.
+	AlternativeText string
+}
+
+func (RichTextCustomEmoji) isRichText() {}
+
+// MarshalJSON implements json.Marshaler.
+//
+// Since: Bot API 10.1
+func (v RichTextCustomEmoji) MarshalJSON() ([]byte, error) {
+	return json.Marshal(struct {
+		Type            string `json:"type"`
+		CustomEmojiID   string `json:"custom_emoji_id"`
+		AlternativeText string `json:"alternative_text"`
+	}{"custom_emoji", v.CustomEmojiID, v.AlternativeText})
+}
+
+// RichTextMathematicalExpression is an inline mathematical expression leaf.
+//
+// Since: Bot API 10.1
+type RichTextMathematicalExpression struct {
+	// Expression contains the mathematical expression source.
+	Expression string
+}
+
+func (RichTextMathematicalExpression) isRichText() {}
+
+// MarshalJSON implements json.Marshaler.
+//
+// Since: Bot API 10.1
+func (v RichTextMathematicalExpression) MarshalJSON() ([]byte, error) {
+	return json.Marshal(struct {
+		Type       string `json:"type"`
+		Expression string `json:"expression"`
+	}{"mathematical_expression", v.Expression})
+}
+
+// RichTextAnchor is a named anchor leaf that anchor links can point to.
+//
+// Since: Bot API 10.1
+type RichTextAnchor struct {
+	// Name is the user-facing or reference name of the value.
+	Name string
+}
+
+func (RichTextAnchor) isRichText() {}
+
+// MarshalJSON implements json.Marshaler.
+//
+// Since: Bot API 10.1
+func (v RichTextAnchor) MarshalJSON() ([]byte, error) {
+	return json.Marshal(struct {
+		Type string `json:"type"`
+		Name string `json:"name"`
+	}{"anchor", v.Name})
+}

tgapi/rich_text_types_test.go

@@ -0,0 +1,85 @@
+package tgapi
+
+import (
+	"encoding/json"
+	"testing"
+)
+
+func roundtripRichText(t *testing.T, in RichText) {
+	t.Helper()
+	b, err := json.Marshal(in)
+	if err != nil {
+		t.Fatalf("marshal: %v", err)
+	}
+	out, err := UnmarshalRichText(b)
+	if err != nil {
+		t.Fatalf("unmarshal %s: %v", b, err)
+	}
+	b2, err := json.Marshal(out)
+	if err != nil {
+		t.Fatalf("remarshal: %v", err)
+	}
+	if string(b) != string(b2) {
+		t.Fatalf("not stable:\n  %s\n  %s", b, b2)
+	}
+}
+
+func TestRichTextRoundtrip(t *testing.T) {
+	cases := []RichText{
+		RichTextPlain("hello"),
+		RichTextArray{RichTextPlain("a "), RichTextWrap{"bold", RichTextPlain("b")}, RichTextPlain(" c")},
+		RichTextWrap{"bold", RichTextWrap{"italic", RichTextPlain("nested")}},
+		RichTextURL{RichTextPlain("Anthropic"), "https://anthropic.com"},
+		RichTextCustomEmoji{"5368324170671202286", "👍"},
+		RichTextMathematicalExpression{"x^2 + y^2"},
+		RichTextAnchor{"chapter-1"},
+		RichTextDateTime{RichTextPlain("22:45 tomorrow"), 1647531900, "wDT"},
+		RichTextTextMention{RichTextPlain("Bob"), User{ID: 42, FirstName: "Bob"}},
+		RichTextAnchorLink{RichTextPlain("back to top"), ""},
+		RichTextReference{RichTextPlain("ref"), "note-1"},
+		// deep nesting
+		RichTextWrap{"bold", RichTextArray{
+			RichTextPlain("bold and "),
+			RichTextWrap{"italic", RichTextWrap{"underline", RichTextPlain("deep")}},
+			RichTextWrap{"spoiler", RichTextCustomEmoji{"1", "x"}},
+		}},
+	}
+	for _, c := range cases {
+		roundtripRichText(t, c)
+	}
+}
+
+func TestRichTextPlainFormsAreBare(t *testing.T) {
+	b, _ := json.Marshal(RichTextPlain("hi"))
+	if string(b) != `"hi"` {
+		t.Fatalf("string should be bare: %s", b)
+	}
+	b, _ = json.Marshal(RichTextArray{RichTextPlain("a"), RichTextPlain("b")})
+	if string(b) != `["a","b"]` {
+		t.Fatalf("array should be bare: %s", b)
+	}
+}
+
+func TestRichTextLeafHasNoText(t *testing.T) {
+	b, _ := json.Marshal(RichTextAnchor{"x"})
+	var m map[string]any
+	_ = json.Unmarshal(b, &m)
+	if _, ok := m["text"]; ok {
+		t.Fatalf("anchor must not have text field: %s", b)
+	}
+}
+
+func TestUnmarshalRichTextRejectsInvalidValues(t *testing.T) {
+	tests := []string{
+		`null`,
+		`{"type":"date_time","text":"now","unix_time":"soon"}`,
+		`{"type":"custom_emoji","custom_emoji_id":42}`,
+	}
+	for _, raw := range tests {
+		t.Run(raw, func(t *testing.T) {
+			if _, err := UnmarshalRichText([]byte(raw)); err == nil {
+				t.Fatal("expected malformed rich text to be rejected")
+			}
+		})
+	}
+}

tgapi/rich_utils.go

@@ -0,0 +1,514 @@
+package tgapi
+
+import (
+	"bytes"
+	"encoding/json"
+	"fmt"
+)
+
+// UnmarshalRichText parses a RichText tree from JSON: a string, an array, or
+// a typed object. Unknown object types that carry a text field are preserved
+// as RichTextWrap so their nested text remains usable; unmodeled fields are
+// discarded.
+//
+// Since: Bot API 10.1
+func UnmarshalRichText(data []byte) (RichText, error) {
+	if bytes.Equal(bytes.TrimSpace(data), []byte("null")) {
+		return nil, fmt.Errorf("richtext: null is not a rich text value")
+	}
+	// 1. string
+	var s string
+	if err := json.Unmarshal(data, &s); err == nil {
+		return RichTextPlain(s), nil
+	}
+	// 2. array
+	var raw []json.RawMessage
+	if err := json.Unmarshal(data, &raw); err == nil {
+		arr := make(RichTextArray, len(raw))
+		for i, it := range raw {
+			rt, err := UnmarshalRichText(it)
+			if err != nil {
+				return nil, err
+			}
+			arr[i] = rt
+		}
+		return arr, nil
+	}
+	// 3. object -> dispatch on type, grabbing the raw text along the way
+	var head struct {
+		Type string          `json:"type"`
+		Text json.RawMessage `json:"text"`
+	}
+	if err := json.Unmarshal(data, &head); err != nil {
+		return nil, fmt.Errorf("richtext: not a string, array or object: %w", err)
+	}
+
+	// Recursively parse the nested text, if any.
+	var inner RichText
+	if len(head.Text) > 0 {
+		var err error
+		if inner, err = UnmarshalRichText(head.Text); err != nil {
+			return nil, fmt.Errorf("richtext %q: bad text: %w", head.Type, err)
+		}
+	}
+
+	if richTextWrapTags[head.Type] {
+		return RichTextWrap{Tag: head.Type, Text: inner}, nil
+	}
+
+	switch head.Type {
+	case "url":
+		var v struct {
+			URL string `json:"url"`
+		}
+		if err := json.Unmarshal(data, &v); err != nil {
+			return nil, err
+		}
+		return RichTextURL{inner, v.URL}, nil
+	case "email_address":
+		var v struct {
+			V string `json:"email_address"`
+		}
+		if err := json.Unmarshal(data, &v); err != nil {
+			return nil, err
+		}
+		return RichTextEmailAddress{inner, v.V}, nil
+	case "phone_number":
+		var v struct {
+			V string `json:"phone_number"`
+		}
+		if err := json.Unmarshal(data, &v); err != nil {
+			return nil, err
+		}
+		return RichTextPhoneNumber{inner, v.V}, nil
+	case "bank_card_number":
+		var v struct {
+			V string `json:"bank_card_number"`
+		}
+		if err := json.Unmarshal(data, &v); err != nil {
+			return nil, err
+		}
+		return RichTextBankCardNumber{inner, v.V}, nil
+	case "mention":
+		var v struct {
+			V string `json:"username"`
+		}
+		if err := json.Unmarshal(data, &v); err != nil {
+			return nil, err
+		}
+		return RichTextMention{inner, v.V}, nil
+	case "hashtag":
+		var v struct {
+			V string `json:"hashtag"`
+		}
+		if err := json.Unmarshal(data, &v); err != nil {
+			return nil, err
+		}
+		return RichTextHashtag{inner, v.V}, nil
+	case "cashtag":
+		var v struct {
+			V string `json:"cashtag"`
+		}
+		if err := json.Unmarshal(data, &v); err != nil {
+			return nil, err
+		}
+		return RichTextCashtag{inner, v.V}, nil
+	case "bot_command":
+		var v struct {
+			V string `json:"bot_command"`
+		}
+		if err := json.Unmarshal(data, &v); err != nil {
+			return nil, err
+		}
+		return RichTextBotCommand{inner, v.V}, nil
+	case "anchor_link":
+		var v struct {
+			V string `json:"anchor_name"`
+		}
+		if err := json.Unmarshal(data, &v); err != nil {
+			return nil, err
+		}
+		return RichTextAnchorLink{inner, v.V}, nil
+	case "reference":
+		var v struct {
+			V string `json:"name"`
+		}
+		if err := json.Unmarshal(data, &v); err != nil {
+			return nil, err
+		}
+		return RichTextReference{inner, v.V}, nil
+	case "reference_link":
+		var v struct {
+			V string `json:"reference_name"`
+		}
+		if err := json.Unmarshal(data, &v); err != nil {
+			return nil, err
+		}
+		return RichTextReferenceLink{inner, v.V}, nil
+	case "date_time":
+		var v struct {
+			UnixTime       int64  `json:"unix_time"`
+			DateTimeFormat string `json:"date_time_format"`
+		}
+		if err := json.Unmarshal(data, &v); err != nil {
+			return nil, err
+		}
+		return RichTextDateTime{inner, v.UnixTime, v.DateTimeFormat}, nil
+	case "text_mention":
+		var v struct {
+			User User `json:"user"`
+		}
+		if err := json.Unmarshal(data, &v); err != nil {
+			return nil, err
+		}
+		return RichTextTextMention{inner, v.User}, nil
+
+	// --- leaves without text ---
+	case "custom_emoji":
+		var v struct {
+			ID  string `json:"custom_emoji_id"`
+			Alt string `json:"alternative_text"`
+		}
+		if err := json.Unmarshal(data, &v); err != nil {
+			return nil, err
+		}
+		return RichTextCustomEmoji{v.ID, v.Alt}, nil
+	case "mathematical_expression":
+		var v struct {
+			Expression string `json:"expression"`
+		}
+		if err := json.Unmarshal(data, &v); err != nil {
+			return nil, err
+		}
+		return RichTextMathematicalExpression{v.Expression}, nil
+	case "anchor":
+		var v struct {
+			Name string `json:"name"`
+		}
+		if err := json.Unmarshal(data, &v); err != nil {
+			return nil, err
+		}
+		return RichTextAnchor{v.Name}, nil
+
+	default:
+		// forward-compat: keep an unknown tag with a text field as
+		// RichTextWrap; without text it is an error (the shape cannot be guessed).
+		if inner != nil {
+			return RichTextWrap{Tag: head.Type, Text: inner}, nil
+		}
+		return nil, fmt.Errorf("richtext: unknown type %q", head.Type)
+	}
+}
+
+// UnmarshalRichBlock parses a single RichBlock from JSON, dispatching on the
+// type tag. Unknown types that carry a text field are decoded as RichBlockWrap
+// so their nested text remains usable; unmodeled fields are discarded.
+//
+// Since: Bot API 10.1
+func UnmarshalRichBlock(data []byte) (RichBlock, error) {
+	var head struct {
+		Type string          `json:"type"`
+		Text json.RawMessage `json:"text"`
+	}
+	if err := json.Unmarshal(data, &head); err != nil {
+		return nil, fmt.Errorf("richblock: %w", err)
+	}
+
+	if richBlockWrapTags[head.Type] {
+		text, err := parseOptRichText(head.Text)
+		if err != nil {
+			return nil, fmt.Errorf("richblock %q: text: %w", head.Type, err)
+		}
+		return RichBlockWrap{Tag: head.Type, Text: text}, nil
+	}
+
+	switch head.Type {
+	case "heading":
+		var v struct {
+			Size int `json:"size"`
+		}
+		if err := json.Unmarshal(data, &v); err != nil {
+			return nil, err
+		}
+		text, err := parseOptRichText(head.Text)
+		if err != nil {
+			return nil, fmt.Errorf("richblock %q: text: %w", head.Type, err)
+		}
+		return RichBlockSectionHeading{text, v.Size}, nil
+
+	case "pre":
+		var v struct {
+			Language string `json:"language"`
+		}
+		if err := json.Unmarshal(data, &v); err != nil {
+			return nil, err
+		}
+		text, err := parseOptRichText(head.Text)
+		if err != nil {
+			return nil, fmt.Errorf("richblock %q: text: %w", head.Type, err)
+		}
+		return RichBlockPreformatted{text, v.Language}, nil
+
+	case "blockquote":
+		var raw struct {
+			Blocks json.RawMessage `json:"blocks"`
+			Credit json.RawMessage `json:"credit"`
+		}
+		if err := json.Unmarshal(data, &raw); err != nil {
+			return nil, err
+		}
+		blocks, err := unmarshalRichBlocks(raw.Blocks)
+		if err != nil {
+			return nil, err
+		}
+		credit, err := parseOptRichText(raw.Credit)
+		if err != nil {
+			return nil, fmt.Errorf("richblock %q: credit: %w", head.Type, err)
+		}
+		return RichBlockQuotation{blocks, credit}, nil
+
+	case "pullquote":
+		var raw struct {
+			Credit json.RawMessage `json:"credit"`
+		}
+		if err := json.Unmarshal(data, &raw); err != nil {
+			return nil, err
+		}
+		text, err := parseOptRichText(head.Text)
+		if err != nil {
+			return nil, fmt.Errorf("richblock %q: text: %w", head.Type, err)
+		}
+		credit, err := parseOptRichText(raw.Credit)
+		if err != nil {
+			return nil, fmt.Errorf("richblock %q: credit: %w", head.Type, err)
+		}
+		return RichBlockPullQuotation{text, credit}, nil
+
+	case "list":
+		var v struct {
+			Items []RichBlockListItem `json:"items"`
+		}
+		if err := json.Unmarshal(data, &v); err != nil {
+			return nil, err
+		}
+		return RichBlockList{v.Items}, nil
+
+	case "collage":
+		var raw struct {
+			Blocks  json.RawMessage   `json:"blocks"`
+			Caption *RichBlockCaption `json:"caption"`
+		}
+		if err := json.Unmarshal(data, &raw); err != nil {
+			return nil, err
+		}
+		blocks, err := unmarshalRichBlocks(raw.Blocks)
+		if err != nil {
+			return nil, err
+		}
+		return RichBlockCollage{blocks, raw.Caption}, nil
+
+	case "slideshow":
+		var raw struct {
+			Blocks  json.RawMessage   `json:"blocks"`
+			Caption *RichBlockCaption `json:"caption"`
+		}
+		if err := json.Unmarshal(data, &raw); err != nil {
+			return nil, err
+		}
+		blocks, err := unmarshalRichBlocks(raw.Blocks)
+		if err != nil {
+			return nil, err
+		}
+		return RichBlockSlideshow{blocks, raw.Caption}, nil
+
+	case "details":
+		var raw struct {
+			Summary json.RawMessage `json:"summary"`
+			Blocks  json.RawMessage `json:"blocks"`
+			IsOpen  bool            `json:"is_open"`
+		}
+		if err := json.Unmarshal(data, &raw); err != nil {
+			return nil, err
+		}
+		summary, err := parseOptRichText(raw.Summary)
+		if err != nil {
+			return nil, fmt.Errorf("richblock %q: summary: %w", head.Type, err)
+		}
+		blocks, err := unmarshalRichBlocks(raw.Blocks)
+		if err != nil {
+			return nil, err
+		}
+		return RichBlockDetails{summary, blocks, raw.IsOpen}, nil
+
+	case "table":
+		var raw struct {
+			Cells      [][]RichBlockTableCell `json:"cells"`
+			IsBordered bool                   `json:"is_bordered"`
+			IsStriped  bool                   `json:"is_striped"`
+			Caption    json.RawMessage        `json:"caption"`
+		}
+		if err := json.Unmarshal(data, &raw); err != nil {
+			return nil, err
+		}
+		caption, err := parseOptRichText(raw.Caption)
+		if err != nil {
+			return nil, fmt.Errorf("richblock %q: caption: %w", head.Type, err)
+		}
+		return RichBlockTable{raw.Cells, raw.IsBordered, raw.IsStriped, caption}, nil
+
+	case "map":
+		var v struct {
+			Location Location          `json:"location"`
+			Zoom     int               `json:"zoom"`
+			Width    int               `json:"width"`
+			Height   int               `json:"height"`
+			Caption  *RichBlockCaption `json:"caption"`
+		}
+		if err := json.Unmarshal(data, &v); err != nil {
+			return nil, err
+		}
+		return RichBlockMap{v.Location, v.Zoom, v.Width, v.Height, v.Caption}, nil
+
+	case "photo":
+		var v struct {
+			Photo      []PhotoSize       `json:"photo"`
+			HasSpoiler bool              `json:"has_spoiler"`
+			Caption    *RichBlockCaption `json:"caption"`
+		}
+		if err := json.Unmarshal(data, &v); err != nil {
+			return nil, err
+		}
+		return RichBlockPhoto{v.Photo, v.HasSpoiler, v.Caption}, nil
+
+	case "video":
+		var v struct {
+			Video      Video             `json:"video"`
+			HasSpoiler bool              `json:"has_spoiler"`
+			Caption    *RichBlockCaption `json:"caption"`
+		}
+		if err := json.Unmarshal(data, &v); err != nil {
+			return nil, err
+		}
+		return RichBlockVideo{v.Video, v.HasSpoiler, v.Caption}, nil
+
+	case "audio":
+		var v struct {
+			Audio   Audio             `json:"audio"`
+			Caption *RichBlockCaption `json:"caption"`
+		}
+		if err := json.Unmarshal(data, &v); err != nil {
+			return nil, err
+		}
+		return RichBlockAudio{v.Audio, v.Caption}, nil
+
+	case "animation":
+		var v struct {
+			Animation  Animation         `json:"animation"`
+			HasSpoiler bool              `json:"has_spoiler"`
+			Caption    *RichBlockCaption `json:"caption"`
+		}
+		if err := json.Unmarshal(data, &v); err != nil {
+			return nil, err
+		}
+		return RichBlockAnimation{v.Animation, v.HasSpoiler, v.Caption}, nil
+
+	case "voice_note":
+		var v struct {
+			VoiceNote Voice             `json:"voice_note"`
+			Caption   *RichBlockCaption `json:"caption"`
+		}
+		if err := json.Unmarshal(data, &v); err != nil {
+			return nil, err
+		}
+		return RichBlockVoiceNote{v.VoiceNote, v.Caption}, nil
+
+	case "divider":
+		return RichBlockDivider{}, nil
+
+	case "mathematical_expression":
+		var v struct {
+			Expression string `json:"expression"`
+		}
+		if err := json.Unmarshal(data, &v); err != nil {
+			return nil, err
+		}
+		return RichBlockMathematicalExpression{v.Expression}, nil
+
+	case "anchor":
+		var v struct {
+			Name string `json:"name"`
+		}
+		if err := json.Unmarshal(data, &v); err != nil {
+			return nil, err
+		}
+		return RichBlockAnchor{v.Name}, nil
+
+	default:
+		// forward-compat: unknown type with text -> RichBlockWrap, without text -> error.
+		if text, err := parseOptRichText(head.Text); err == nil && text != nil {
+			return RichBlockWrap{Tag: head.Type, Text: text}, nil
+		}
+		return nil, fmt.Errorf("richblock: unknown type %q", head.Type)
+	}
+}
+
+// UnmarshalRichMessage parses a root RichMessage from JSON.
+//
+// Since: Bot API 10.1
+func UnmarshalRichMessage(data []byte) (RichMessage, error) {
+	var raw struct {
+		Blocks json.RawMessage `json:"blocks"`
+		IsRTL  bool            `json:"is_rtl"`
+	}
+	if err := json.Unmarshal(data, &raw); err != nil {
+		return RichMessage{}, fmt.Errorf("richmessage: %w", err)
+	}
+	blocks, err := unmarshalRichBlocks(raw.Blocks)
+	if err != nil {
+		return RichMessage{}, err
+	}
+	return RichMessage{blocks, raw.IsRTL}, nil
+}
+
+// UnmarshalJSON implements json.Unmarshaler.
+//
+// Since: Bot API 10.1
+func (m *RichMessage) UnmarshalJSON(data []byte) error {
+	parsed, err := UnmarshalRichMessage(data)
+	if err != nil {
+		return err
+	}
+	*m = parsed
+	return nil
+}
+
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+
+// Optional RichText fields treat absent and null values as nil.
+func parseOptRichText(raw json.RawMessage) (RichText, error) {
+	if len(raw) == 0 || string(raw) == "null" {
+		return nil, nil
+	}
+	return UnmarshalRichText(raw)
+}
+
+func unmarshalRichBlocks(raw json.RawMessage) ([]RichBlock, error) {
+	if len(raw) == 0 || string(raw) == "null" {
+		return nil, nil
+	}
+	var raws []json.RawMessage
+	if err := json.Unmarshal(raw, &raws); err != nil {
+		return nil, err
+	}
+	blocks := make([]RichBlock, len(raws))
+	for i, r := range raws {
+		b, err := UnmarshalRichBlock(r)
+		if err != nil {
+			return nil, err
+		}
+		blocks[i] = b
+	}
+	return blocks, nil
+}

tgapi/rich_utils_test.go

@@ -0,0 +1,268 @@
+package tgapi
+
+import (
+	"encoding/json"
+	"strings"
+	"testing"
+)
+
+func roundtripRichBlock(t *testing.T, in RichBlock) {
+	t.Helper()
+	b, err := json.Marshal(in)
+	if err != nil {
+		t.Fatalf("marshal: %v", err)
+	}
+	out, err := UnmarshalRichBlock(b)
+	if err != nil {
+		t.Fatalf("unmarshal %s: %v", b, err)
+	}
+	b2, err := json.Marshal(out)
+	if err != nil {
+		t.Fatalf("remarshal: %v", err)
+	}
+	if string(b) != string(b2) {
+		t.Fatalf("not stable:\n  %s\n  %s", b, b2)
+	}
+}
+
+func par(s string) RichBlockWrap { return RichBlockWrap{"paragraph", RichTextPlain(s)} }
+
+func TestRichBlockRoundtrip(t *testing.T) {
+	cases := []RichBlock{
+		// wrap blocks
+		par("Hello, world"),
+		RichBlockWrap{"footer", RichTextPlain("© 2024")},
+		RichBlockWrap{"thinking", RichTextPlain("Let me reason step by step.")},
+
+		// heading
+		RichBlockSectionHeading{RichTextWrap{"bold", RichTextPlain("Chapter 1")}, 1},
+		RichBlockSectionHeading{RichTextPlain("smallest"), 6},
+
+		// preformatted
+		RichBlockPreformatted{RichTextPlain(`fmt.Println("hi")`), "go"},
+		RichBlockPreformatted{Text: RichTextPlain("no language")},
+
+		// quotations
+		RichBlockQuotation{[]RichBlock{par("To be or not to be")}, RichTextPlain("Shakespeare")},
+		RichBlockQuotation{Blocks: []RichBlock{par("anonymous"), par("second block")}},
+		RichBlockPullQuotation{Text: RichTextPlain("Pull me")},
+		RichBlockPullQuotation{RichTextPlain("Wisdom"), RichTextWrap{"italic", RichTextPlain("someone")}},
+
+		// list: label is the ready-made marker, numbering lives on the items
+		RichBlockList{
+			Items: []RichBlockListItem{
+				{Label: "c.", Blocks: []RichBlock{par("item 3")}, Value: 3, Type: "a"},
+				{Label: "vii.", Blocks: []RichBlock{par("item 7")}, Value: 7, Type: "i"},
+			},
+		},
+		RichBlockList{
+			Items: []RichBlockListItem{
+				{Label: "•", Blocks: []RichBlock{par("todo")}, HasCheckbox: true},
+				{Label: "•", Blocks: []RichBlock{par("done")}, HasCheckbox: true, IsChecked: true},
+			},
+		},
+
+		// collage and slideshow
+		RichBlockCollage{
+			Blocks:  []RichBlock{RichBlockPhoto{Photo: []PhotoSize{{FileID: "abc123", Width: 100, Height: 100}}}},
+			Caption: &RichBlockCaption{Text: RichTextPlain("A photo")},
+		},
+		RichBlockSlideshow{
+			Blocks: []RichBlock{
+				RichBlockVideo{Video: Video{FileID: "vid1", Width: 640, Height: 480, Duration: 10}},
+			},
+		},
+
+		// details
+		RichBlockDetails{
+			Summary: RichTextPlain("Spoiler"),
+			Blocks:  []RichBlock{par("Hidden content")},
+		},
+		RichBlockDetails{
+			Summary: RichTextWrap{"bold", RichTextPlain("Open details")},
+			Blocks:  []RichBlock{RichBlockDivider{}, par("content")},
+			IsOpen:  true,
+		},
+
+		// table: text cells, headers, spans, alignment, invisible cell
+		RichBlockTable{
+			Cells: [][]RichBlockTableCell{
+				{
+					{Text: RichTextPlain("Name"), IsHeader: true, Align: "center"},
+					{Text: RichTextPlain("Score"), IsHeader: true, VAlign: "middle"},
+				},
+				{
+					{Text: RichTextPlain("Alice"), ColSpan: 2},
+				},
+				{
+					{}, // invisible cell
+					{Text: RichTextPlain("42"), RowSpan: 2},
+				},
+			},
+			IsBordered: true,
+			Caption:    RichTextPlain("Results"),
+		},
+
+		// map
+		RichBlockMap{
+			Location: Location{Latitude: 55.7558, Longitude: 37.6173},
+			Zoom:     13, Width: 800, Height: 400,
+			Caption: &RichBlockCaption{Text: RichTextPlain("Moscow"), Credit: RichTextPlain("OpenStreetMap")},
+		},
+
+		// media
+		RichBlockPhoto{
+			Photo:      []PhotoSize{{FileID: "p1", Width: 1280, Height: 720}},
+			HasSpoiler: true,
+			Caption:    &RichBlockCaption{Text: RichTextPlain("A cat"), Credit: RichTextWrap{"italic", RichTextPlain("photographer")}},
+		},
+		RichBlockVideo{Video: Video{FileID: "v1", Width: 1920, Height: 1080, Duration: 30}, HasSpoiler: true},
+		RichBlockAudio{
+			Audio:   Audio{FileID: "a1", Duration: 60},
+			Caption: &RichBlockCaption{Text: RichTextPlain("Podcast ep. 1")},
+		},
+		RichBlockAnimation{Animation: Animation{FileID: "g1", Width: 320, Height: 240, Duration: 2}},
+		RichBlockVoiceNote{VoiceNote: Voice{FileID: "vn1", Duration: 5}},
+
+		// leaves
+		RichBlockDivider{},
+		RichBlockMathematicalExpression{Expression: "E = mc^2"},
+		RichBlockAnchor{Name: "section-2"},
+	}
+	for _, c := range cases {
+		roundtripRichBlock(t, c)
+	}
+}
+
+func TestRichMessageRoundtrip(t *testing.T) {
+	for _, msg := range []RichMessage{
+		{
+			Blocks: []RichBlock{
+				RichBlockSectionHeading{RichTextPlain("Title"), 1},
+				RichBlockWrap{"paragraph", RichTextArray{RichTextPlain("Some "), RichTextWrap{"bold", RichTextPlain("bold")}, RichTextPlain(" text")}},
+				RichBlockDivider{},
+				RichBlockList{
+					Items: []RichBlockListItem{
+						{Label: "1.", Blocks: []RichBlock{par("First")}, Value: 1, Type: "1"},
+						{Label: "2.", Blocks: []RichBlock{par("Second")}, Value: 2, Type: "1"},
+					},
+				},
+				RichBlockPhoto{
+					Photo:   []PhotoSize{{FileID: "img1", Width: 10, Height: 10}},
+					Caption: &RichBlockCaption{Text: RichTextPlain("Fig. 1")},
+				},
+			},
+		},
+		{
+			Blocks: []RichBlock{par("שלום")},
+			IsRTL:  true,
+		},
+	} {
+		b, err := json.Marshal(msg)
+		if err != nil {
+			t.Fatalf("marshal: %v", err)
+		}
+		var out RichMessage
+		if err := json.Unmarshal(b, &out); err != nil {
+			t.Fatalf("unmarshal: %v", err)
+		}
+		b2, err := json.Marshal(out)
+		if err != nil {
+			t.Fatalf("remarshal: %v", err)
+		}
+		if string(b) != string(b2) {
+			t.Fatalf("not stable:\n  %s\n  %s", b, b2)
+		}
+	}
+}
+
+func TestRichBlockTags(t *testing.T) {
+	// tags per spec: heading, pre, blockquote, pullquote
+	cases := map[string]RichBlock{
+		"heading":    RichBlockSectionHeading{RichTextPlain("h"), 2},
+		"pre":        RichBlockPreformatted{Text: RichTextPlain("x")},
+		"blockquote": RichBlockQuotation{Blocks: []RichBlock{par("q")}},
+		"pullquote":  RichBlockPullQuotation{Text: RichTextPlain("p")},
+	}
+	for want, block := range cases {
+		b, _ := json.Marshal(block)
+		var m map[string]any
+		_ = json.Unmarshal(b, &m)
+		if m["type"] != want {
+			t.Fatalf("expected type %q, got %s", want, b)
+		}
+	}
+}
+
+func TestRichBlockOptionalFieldsOmitted(t *testing.T) {
+	// nil credit/caption and false flags must not appear in the JSON
+	for _, c := range []struct {
+		block RichBlock
+		bad   []string
+	}{
+		{RichBlockQuotation{Blocks: []RichBlock{par("q")}}, []string{"credit"}},
+		{RichBlockPullQuotation{Text: RichTextPlain("p")}, []string{"credit"}},
+		{RichBlockPhoto{Photo: []PhotoSize{{FileID: "p"}}}, []string{"caption", "has_spoiler"}},
+		{RichBlockTable{Cells: [][]RichBlockTableCell{}}, []string{"caption", "is_bordered", "is_striped"}},
+		{RichBlockDetails{Summary: RichTextPlain("s")}, []string{"is_open"}},
+	} {
+		b, _ := json.Marshal(c.block)
+		for _, key := range c.bad {
+			if strings.Contains(string(b), `"`+key+`"`) {
+				t.Fatalf("%T: %q must be omitted: %s", c.block, key, b)
+			}
+		}
+	}
+	// same for RichMessage.is_rtl
+	b, _ := json.Marshal(RichMessage{Blocks: []RichBlock{par("x")}})
+	if strings.Contains(string(b), "is_rtl") {
+		t.Fatalf("is_rtl must be omitted: %s", b)
+	}
+}
+
+func TestRichBlockDividerHasNoContent(t *testing.T) {
+	b, _ := json.Marshal(RichBlockDivider{})
+	var m map[string]any
+	_ = json.Unmarshal(b, &m)
+	if len(m) != 1 {
+		t.Fatalf("divider must only have type field: %s", b)
+	}
+	if m["type"] != "divider" {
+		t.Fatalf("unexpected type: %s", b)
+	}
+}
+
+func TestRichBlockUnknownTypeWithTextIsForwardCompat(t *testing.T) {
+	raw := []byte(`{"type":"future_tag","text":"hello"}`)
+	b, err := UnmarshalRichBlock(raw)
+	if err != nil {
+		t.Fatalf("forward-compat failed: %v", err)
+	}
+	w, ok := b.(RichBlockWrap)
+	if !ok || w.Tag != "future_tag" {
+		t.Fatalf("expected RichBlockWrap{future_tag}, got %T", b)
+	}
+}
+
+func TestRichBlockUnknownTypeWithoutTextIsError(t *testing.T) {
+	raw := []byte(`{"type":"mystery_leaf","value":42}`)
+	_, err := UnmarshalRichBlock(raw)
+	if err == nil {
+		t.Fatal("expected error for unknown type without text")
+	}
+}
+
+func TestUnmarshalRichBlockRejectsMalformedFields(t *testing.T) {
+	tests := []string{
+		`{"type":"heading","size":"large","text":"hello"}`,
+		`{"type":"blockquote","blocks":[],"credit":{"type":"date_time","text":"now","unix_time":"soon"}}`,
+		`{"type":"table","cells":[],"caption":{"type":"date_time","text":"now","unix_time":"soon"}}`,
+	}
+	for _, raw := range tests {
+		t.Run(raw, func(t *testing.T) {
+			if _, err := UnmarshalRichBlock([]byte(raw)); err == nil {
+				t.Fatal("expected malformed rich block to be rejected")
+			}
+		})
+	}
+}

tgapi/stars_methods.go

@@ -0,0 +1,98 @@
+package tgapi
+
+import "context"
+
+// GetStarTransactions holds parameters for the getStarTransactions method.
+// Since: Bot API 7.5
+// See https://core.telegram.org/bots/api#getstartransactions
+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)
+	return req.Do(api)
+}
+
+// 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) {
+	req := NewRequest[StarAmount]("getMyStarBalance", NoParams)
+	return req.DoWithContext(ctx, api)
+}
+
+// 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 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 GetStarTransactions) (StarTransactions, error) {
+	req := NewRequest[StarTransactions]("getStarTransactions", params)
+	return req.DoWithContext(ctx, api)
+}
+
+// RefundStarPayment holds parameters for the refundStarPayment method.
+// Since: Bot API 7.4
+// See https://core.telegram.org/bots/api#refundstarpayment
+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 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 RefundStarPayment) (bool, error) {
+	req := NewRequest[bool]("refundStarPayment", params)
+	return req.DoWithContext(ctx, api)
+}
+
+// EditUserStarSubscription holds parameters for the editUserStarSubscription method.
+// Since: Bot API 8.0
+// See https://core.telegram.org/bots/api#edituserstarsubscription
+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 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 EditUserStarSubscription) (bool, error) {
+	req := NewRequest[bool]("editUserStarSubscription", params)
+	return req.DoWithContext(ctx, api)
+}

tgapi/stars_types.go

@@ -0,0 +1,20 @@
+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"`
+	Amount         int            `json:"amount"`
+	NanostarAmount int            `json:"nanostar_amount,omitempty"`
+	Date           int            `json:"date"`
+	Source         map[string]any `json:"source,omitempty"`
+	Receiver       map[string]any `json:"receiver,omitempty"`
+}
+
+// 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

@@ -1,10 +1,19 @@
 package tgapi
 
-type SendStickerP struct {
+import "context"
+
+// SendSticker holds parameters for the sendSticker method.
+// Since: Bot API 1.3
+// See https://core.telegram.org/bots/api#sendsticker
+type SendSticker struct {
 	BusinessConnectionID  string `json:"business_connection_id,omitempty"`
-	ChatID                int    `json:"chat_id"`
+	ChatID                int64  `json:"chat_id"`
 	MessageThreadID       int    `json:"message_thread_id,omitempty"`
 	DirectMessagesTopicID int    `json:"direct_messages_topic_id,omitempty"`
+	// ReceiverUserID identifies the user who can see the ephemeral message.
+	ReceiverUserID int64 `json:"receiver_user_id,omitempty"` // Since: Bot API 10.2
+	// CallbackQueryID identifies the callback query that triggered an ephemeral response.
+	CallbackQueryID string `json:"callback_query_id,omitempty"` // Since: Bot API 10.2
 
 	Sticker             string `json:"sticker"`
 	Emoji               string `json:"emoji,omitempty"`
@@ -12,33 +21,116 @@ type SendStickerP struct {
 	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"`
 }
 
-func (api *API) SendSticker(params SendStickerP) (Message, error) {
-	req := NewRequest[Message]("sendSticker", params)
+// 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 SendSticker) (Message, error) {
+	req := NewRequestWithChatID[Message]("sendSticker", params, params.ChatID)
 	return req.Do(api)
 }
 
-type GetStickerSetP struct {
+// 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 SendSticker) (Message, error) {
+	req := NewRequestWithChatID[Message]("sendSticker", params, params.ChatID)
+	return req.DoWithContext(ctx, api)
+}
+
+// GetStickerSet holds parameters for the getStickerSet method.
+// Since: Bot API 3.2
+// See https://core.telegram.org/bots/api#getstickerset
+type GetStickerSet struct {
 	Name string `json:"name"`
 }
 
-func (api *API) GetStickerSet(params GetStickerSetP) (StickerSet, error) {
+// 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 GetStickerSet) (StickerSet, error) {
 	req := NewRequest[StickerSet]("getStickerSet", params)
 	return req.Do(api)
 }
 
-type GetCustomEmojiStickersP struct {
+// 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 GetStickerSet) (StickerSet, error) {
+	req := NewRequest[StickerSet]("getStickerSet", params)
+	return req.DoWithContext(ctx, api)
+}
+
+// GetCustomEmojiStickers holds parameters for the getCustomEmojiStickers method.
+// Since: Bot API 6.2
+// See https://core.telegram.org/bots/api#getcustomemojistickers
+type GetCustomEmojiStickers struct {
 	CustomEmojiIDs []string `json:"custom_emoji_ids"`
 }
 
-func (api *API) GetCustomEmojiStickers(params GetCustomEmojiStickersP) ([]Sticker, error) {
+// 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 GetCustomEmojiStickers) ([]Sticker, error) {
 	req := NewRequest[[]Sticker]("getCustomEmojiStickers", params)
 	return req.Do(api)
 }
 
-type CreateNewStickerSetP struct {
-	UserID int    `json:"user_id"`
+// 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 GetCustomEmojiStickers) ([]Sticker, error) {
+	req := NewRequest[[]Sticker]("getCustomEmojiStickers", params)
+	return req.DoWithContext(ctx, api)
+}
+
+// UploadStickerFile holds parameters for the uploadStickerFile method.
+// Since: Bot API 3.2
+// See https://core.telegram.org/bots/api#uploadstickerfile
+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 UploadStickerFile, sticker UploaderFile) (File, error) {
+	uploader := NewUploader(api)
+	defer func() {
+		_ = uploader.Close()
+	}()
+	req := NewUploaderRequest[File]("uploadStickerFile", params, sticker.SetType(UploaderStickerType))
+	return req.Do(uploader)
+}
+
+// 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 UploadStickerFile, sticker UploaderFile) (File, error) {
+	uploader := NewUploader(api)
+	defer func() {
+		_ = uploader.Close()
+	}()
+	req := NewUploaderRequest[File]("uploadStickerFile", params, sticker.SetType(UploaderStickerType))
+	return req.DoWithContext(ctx, uploader)
+}
+
+// CreateNewStickerSet holds parameters for the createNewStickerSet method.
+// Since: Bot API 3.2
+// See https://core.telegram.org/bots/api#createnewstickerset
+type CreateNewStickerSet struct {
+	UserID int64  `json:"user_id"`
 	Name   string `json:"name"`
 	Title  string `json:"title"`
 
@@ -47,120 +139,309 @@ type CreateNewStickerSetP struct {
 	NeedsRepainting bool           `json:"needs_repainting,omitempty"`
 }
 
-func (api *API) CreateNewStickerSet(params CreateNewStickerSetP) (bool, error) {
+// 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 CreateNewStickerSet) (bool, error) {
 	req := NewRequest[bool]("createNewStickerSet", params)
 	return req.Do(api)
 }
 
-type AddStickerToSetP struct {
-	UserID  int          `json:"user_id"`
+// 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 CreateNewStickerSet) (bool, error) {
+	req := NewRequest[bool]("createNewStickerSet", params)
+	return req.DoWithContext(ctx, api)
+}
+
+// AddStickerToSet holds parameters for the addStickerToSet method.
+// Since: Bot API 3.2
+// See https://core.telegram.org/bots/api#addstickertoset
+type AddStickerToSet struct {
+	UserID  int64        `json:"user_id"`
 	Name    string       `json:"name"`
 	Sticker InputSticker `json:"sticker"`
 }
 
-func (api *API) AddStickerToSet(params AddStickerToSetP) (bool, error) {
+// 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 AddStickerToSet) (bool, error) {
 	req := NewRequest[bool]("addStickerToSet", params)
 	return req.Do(api)
 }
 
-type SetStickerPositionInSetP struct {
+// 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 AddStickerToSet) (bool, error) {
+	req := NewRequest[bool]("addStickerToSet", params)
+	return req.DoWithContext(ctx, api)
+}
+
+// SetStickerPositionInSet holds parameters for the setStickerPositionInSet method.
+// Since: Bot API 3.2
+// See https://core.telegram.org/bots/api#setstickerpositioninset
+type SetStickerPositionInSet struct {
 	Sticker  string `json:"sticker"`
 	Position int    `json:"position"`
 }
 
-func (api *API) SetStickerPosition(params SetStickerPositionInSetP) (bool, error) {
-	req := NewRequest[bool]("setStickerPosition", params)
+// 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 SetStickerPositionInSet) (bool, error) {
+	req := NewRequest[bool]("setStickerPositionInSet", params)
 	return req.Do(api)
 }
 
-type DeleteStickerFromSetP struct {
+// 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 SetStickerPositionInSet) (bool, error) {
+	req := NewRequest[bool]("setStickerPositionInSet", params)
+	return req.DoWithContext(ctx, api)
+}
+
+// DeleteStickerFromSet holds parameters for the deleteStickerFromSet method.
+// Since: Bot API 3.2
+// See https://core.telegram.org/bots/api#deletestickerfromset
+type DeleteStickerFromSet struct {
 	Sticker string `json:"sticker"`
 }
 
-func (api *API) DeleteStickerFromSet(params DeleteStickerFromSetP) (bool, error) {
+// 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 DeleteStickerFromSet) (bool, error) {
 	req := NewRequest[bool]("deleteStickerFromSet", params)
 	return req.Do(api)
 }
 
-type ReplaceStickerInSetP struct {
-	UserID     int          `json:"user_id"`
+// 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 DeleteStickerFromSet) (bool, error) {
+	req := NewRequest[bool]("deleteStickerFromSet", params)
+	return req.DoWithContext(ctx, api)
+}
+
+// ReplaceStickerInSet holds parameters for the replaceStickerInSet method.
+// Since: Bot API 7.2
+// See https://core.telegram.org/bots/api#replacestickerinset
+type ReplaceStickerInSet struct {
+	UserID     int64        `json:"user_id"`
 	Name       string       `json:"name"`
 	OldSticker string       `json:"old_sticker"`
 	Sticker    InputSticker `json:"sticker"`
 }
 
-func (api *API) ReplaceStickerInSet(params ReplaceStickerInSetP) (bool, error) {
+// 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 ReplaceStickerInSet) (bool, error) {
 	req := NewRequest[bool]("replaceStickerInSet", params)
 	return req.Do(api)
 }
 
-type SetStickerEmojiListP struct {
+// 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 ReplaceStickerInSet) (bool, error) {
+	req := NewRequest[bool]("replaceStickerInSet", params)
+	return req.DoWithContext(ctx, api)
+}
+
+// SetStickerEmojiList holds parameters for the setStickerEmojiList method.
+// Since: Bot API 6.6
+// See https://core.telegram.org/bots/api#setstickeremojilist
+type SetStickerEmojiList struct {
 	Sticker   string   `json:"sticker"`
 	EmojiList []string `json:"emoji_list"`
 }
 
-func (api *API) SetStickerEmojiList(params SetStickerEmojiListP) (bool, error) {
+// 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 SetStickerEmojiList) (bool, error) {
 	req := NewRequest[bool]("setStickerEmojiList", params)
 	return req.Do(api)
 }
 
-type SetStickerKeywordsP struct {
+// 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 SetStickerEmojiList) (bool, error) {
+	req := NewRequest[bool]("setStickerEmojiList", params)
+	return req.DoWithContext(ctx, api)
+}
+
+// SetStickerKeywords holds parameters for the setStickerKeywords method.
+// Since: Bot API 6.6
+// See https://core.telegram.org/bots/api#setstickerkeywords
+type SetStickerKeywords struct {
 	Sticker  string   `json:"sticker"`
 	Keywords []string `json:"keywords"`
 }
 
-func (api *API) SetStickerKeywords(params SetStickerKeywordsP) (bool, error) {
+// 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 SetStickerKeywords) (bool, error) {
 	req := NewRequest[bool]("setStickerKeywords", params)
 	return req.Do(api)
 }
 
-type SetStickerMaskPositionP struct {
+// 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 SetStickerKeywords) (bool, error) {
+	req := NewRequest[bool]("setStickerKeywords", params)
+	return req.DoWithContext(ctx, api)
+}
+
+// SetStickerMaskPosition holds parameters for the setStickerMaskPosition method.
+// Since: Bot API 6.6
+// See https://core.telegram.org/bots/api#setstickermaskposition
+type SetStickerMaskPosition struct {
 	Sticker      string        `json:"sticker"`
 	MaskPosition *MaskPosition `json:"mask_position,omitempty"`
 }
 
-func (api *API) SetStickerMaskPosition(params SetStickerMaskPositionP) (bool, error) {
+// 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 SetStickerMaskPosition) (bool, error) {
 	req := NewRequest[bool]("setStickerMaskPosition", params)
 	return req.Do(api)
 }
 
-type SetStickerSetTitleP struct {
+// 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 SetStickerMaskPosition) (bool, error) {
+	req := NewRequest[bool]("setStickerMaskPosition", params)
+	return req.DoWithContext(ctx, api)
+}
+
+// SetStickerSetTitle holds parameters for the setStickerSetTitle method.
+// Since: Bot API 6.6
+// See https://core.telegram.org/bots/api#setstickersettitle
+type SetStickerSetTitle struct {
 	Name  string `json:"name"`
 	Title string `json:"title"`
 }
 
-func (api *API) SetStickerSetTitle(params SetStickerSetTitleP) (bool, error) {
+// 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 SetStickerSetTitle) (bool, error) {
 	req := NewRequest[bool]("setStickerSetTitle", params)
 	return req.Do(api)
 }
 
-type SetStickerSetThumbnailP struct {
+// 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 SetStickerSetTitle) (bool, error) {
+	req := NewRequest[bool]("setStickerSetTitle", params)
+	return req.DoWithContext(ctx, api)
+}
+
+// SetStickerSetThumbnail holds parameters for the setStickerSetThumbnail method.
+// Since: Bot API 6.6
+// See https://core.telegram.org/bots/api#setstickersetthumbnail
+type SetStickerSetThumbnail struct {
 	Name      string             `json:"name"`
-	UserID    int                `json:"user_id"`
+	UserID    int64              `json:"user_id"`
 	Thumbnail string             `json:"thumbnail"`
 	Format    InputStickerFormat `json:"format"`
 }
 
-func (api *API) SetStickerSetThumbnail(params SetStickerSetThumbnailP) (bool, error) {
+// 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 SetStickerSetThumbnail) (bool, error) {
 	req := NewRequest[bool]("setStickerSetThumbnail", params)
 	return req.Do(api)
 }
 
-type SetCustomEmojiStickerSetThumbnailP struct {
+// 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 SetStickerSetThumbnail) (bool, error) {
+	req := NewRequest[bool]("setStickerSetThumbnail", params)
+	return req.DoWithContext(ctx, api)
+}
+
+// SetCustomEmojiStickerSetThumbnail holds parameters for the setCustomEmojiStickerSetThumbnail method.
+// Since: Bot API 6.6
+// See https://core.telegram.org/bots/api#setcustomemojistickersetthumbnail
+type SetCustomEmojiStickerSetThumbnail struct {
 	Name          string `json:"name"`
 	CustomEmojiID string `json:"custom_emoji_id,omitempty"`
 }
 
-func (api *API) SetCustomEmojiStickerSetThumbnail(params SetStickerSetThumbnailP) (bool, error) {
+// 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 SetCustomEmojiStickerSetThumbnail) (bool, error) {
 	req := NewRequest[bool]("setCustomEmojiStickerSetThumbnail", params)
 	return req.Do(api)
 }
 
-type DeleteStickerSetP struct {
+// 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 SetCustomEmojiStickerSetThumbnail) (bool, error) {
+	req := NewRequest[bool]("setCustomEmojiStickerSetThumbnail", params)
+	return req.DoWithContext(ctx, api)
+}
+
+// DeleteStickerSet holds parameters for the deleteStickerSet method.
+// Since: Bot API 6.6
+// See https://core.telegram.org/bots/api#deletestickerset
+type DeleteStickerSet struct {
 	Name string `json:"name"`
 }
 
-func (api *API) DeleteStickerSet(params DeleteStickerSetP) (bool, error) {
+// 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 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 DeleteStickerSet) (bool, error) {
+	req := NewRequest[bool]("deleteStickerSet", params)
+	return req.DoWithContext(ctx, api)
+}