Release v1.0.0-rc.12

Finalize scenes, typed arg binding, and request-scoped context plumbing

Refresh docs, backlog state, and regression coverage for the rc.12 release

.gitignore

@@ -1,2 +1,5 @@
 .idea/
-test/
+.wiki/
+.vscode/
+test/
+.codex/

.golangci.yml

@@ -0,0 +1,14 @@
+version: "2"
+run:
+  timeout: 5m
+linters:
+  disable-all: true
+  enable:
+    - errcheck
+    - govet
+    - 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,159 @@
+# AGENTS.md
+
+## Purpose
+This repository uses Codex 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.
+
+## 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.
+
+### 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 do not require a `CHANGELOG.md` update.
+- 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.
+- 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 made in the turn, including API additions, fixes, behavior changes, and breaking changes.
+- When a framework backlog item recorded in `TODO.md` is completed, the agent must also update the backlog status using the existing format:
+  1. move the completed item into the top of the `Done` section;
+  2. replace the numbered backlog label with a version tag, for example `1. Scene Model` becomes `[v2.0.0] Scene Model`;
+  3. keep the item title and descriptive notes aligned with the corresponding `CHANGELOG.md` entry.
+- The agent must treat `TODO.md` and `CHANGELOG.md` as linked records: a completed backlog item should not be left in one file as done and in the other as still pending or undocumented.
+
+## Breaking changes policy
+- The agent must detect potential breaking changes before editing public APIs.
+- Breaking changes are forbidden unless the selected target version is a new major version.
+- If the requested change is breaking and the user did not bump the major version, the agent must stop and warn that the change is not allowed under the current version.
+- In that case, the agent must offer only these options:
+  1. do not make the breaking change;
+  2. introduce a backward-compatible alternative such as a new method, function, type, or struct, but only if that keeps the codebase reasonably small and clear;
+  3. bump the major version and then apply the breaking change.
+- Prefer additive compatibility over signature changes when the additive option is small and maintainable.
+- Example: if a method like `ctx.answer(...)` needs an extra parameter, the agent must either require a major-version bump or add a new method that keeps the old method working.
+
+## Commit message format
+- When the user asks for a commit message, the agent must produce it in this format:
+  1. a short summary line;
+  2. up to three additional lines with only the most important changes;
+  3. each additional line must start on its own new line.
+- 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,191 @@
+# Changelog
+
+## 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,293 @@
 # 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.24+-00ADD8?logo=go&style=flat-square)](https://go.dev/)
+[![License: GPL-3.0](https://img.shields.io/badge/License-GPL%203.0-blue.svg?style=flat-square)](LICENSE)
+![Gitea Release](https://img.shields.io/gitea/v/release/ScuroNeko/Laniakea?gitea_url=https%3A%2F%2Fgit.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 database or state contexts to your handlers.
+*   **Fluent Interface:** Chain methods for clean configuration (e.g., `bot.ErrorTemplate(...).AddPlugins(...)`).
+
+---
+
+## 📦 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.)
+//   - db: your custom database context (here we use NoDB, a placeholder for no database)
+func echo(ctx *laniakea.MsgContext, db laniakea.NoDB) 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.NoDB as the database context type (no database needed for this example).
+	bot, err := laniakea.NewBot[laniakea.NoDB](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.NoDB]("ping")
+
+	// 4. Add a command to the plugin.
+	//    p.NewCommand(echo, "echo") creates a command that triggers the 'echo' function on the "/echo" command.
+	p.AddCommand(p.NewCommand(echo, "echo"))
+
+	// 5. Add another command using an anonymous function (closure).
+	//    This command simply replies "Pong" when the user sends "/ping".
+	p.AddCommand(p.NewCommand(func(ctx *laniakea.MsgContext, db laniakea.NoDB) error {
+		ctx.Answer("Pong")
+		return nil
+	}, "ping"))
+
+	// 6. Configure the bot with a custom error template and add the plugin.
+	//    ErrorTemplate sets a format string for errors (where %s will be replaced by the actual error).
+	//    AddPlugins(p) registers our "ping" plugin with the bot.
+	bot = bot.ErrorTemplate("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 a custom database context (e.g., *sql.DB) that will be available in all handlers. Use laniakea.NoDB if you don't need it.
+3. `NewPlugin`: Creates a logical group for commands and middlewares.
+4. `AddCommand`: Registers a command. The first argument is the handler function (`func(*MsgContext, T) error`), the second is the command name (without the slash).
+5. **Handler Functions**: Receive *MsgContext (message details, methods like Answer) and your custom database context T, and return an error for centralized error handling.
+6. `ErrorTemplate`: Sets a template for error messages. The %s placeholder is replaced by the actual error.
+7. `AutoGenerateCommands`: Registers plugin-defined commands with Telegram across the supported scopes.
+8. `Run()`: Starts the bot's update polling loop and returns an error if startup or polling fails.
+9. A `Bot` instance is single-use. After `Run()` or `RunWithContext()` returns, create a new bot instance for the next session.
+
+## 📖 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.AddCommand(plugin.NewCommand(banUser, "ban"))
+bot.AddPlugins(plugin)
+```
+
+### Commands
+
+A command is a function that handles a specific bot command (e.g., /start).
+```go
+func myHandler(ctx *laniakea.MsgContext, db *MyDB) error {
+    // Access command arguments via ctx.Args ([]string)
+    // Reply to the user: ctx.Answer("some text")
+    return nil
+}
+```
+
+### MsgContext
+
+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)`: Edits message with parse_mode none after clicking inline button.
+- `EditCallbackMarkdown(text string)`: Edits a message formatted with MarkdownV2 (you handle escaping) after clicking inline button.
+- `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.
+
+### Database Context
+
+The `T` in `NewBot[T]` is a powerful feature. You can pass any type, but shared dependencies such as database pools should usually use a pointer type.
+
+```go
+type MyDB struct { /* ... */ }
+db := &MyDB{...}
+bot, err := laniakea.NewBot[*MyDB](opts)
+if err != nil {
+    log.Fatal(err)
+}
+bot.DatabaseContext(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.NewScene("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.
+
+## 🧩 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 *MsgContext, 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.AddCommand(plugin.NewCommand(banUser, "ban"))
+```
+
+### Example Middlewares
+
+1. Logging Middleware – logs every command execution.
+```go
+func loggingMiddleware(ctx *laniakea.MsgContext, 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.MsgContext, 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 MsgContext (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(...)` does 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,289 @@
+# Laniakea
+
+![Laniakea](assets/logo.jpg)
+
+[![Go Version](https://img.shields.io/badge/Go-1.24+-00ADD8?logo=go&style=flat-square)](https://go.dev/)
+[![License: GPL-3.0](https://img.shields.io/badge/License-GPL%203.0-blue.svg?style=flat-square)](LICENSE)
+![Gitea Release](https://img.shields.io/gitea/v/release/ScuroNeko/Laniakea?gitea_url=https%3A%2F%2Fgit.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`).
+*   **Контекст данных:** Передавайте свой контекст базы данных или состояния в обработчики.
+*   **Текучий интерфейс (Fluent Interface):** Стройте цепочки методов для чистой конфигурации (например, `bot.ErrorTemplate(...).AddPlugins(...)`).
+
+---
+
+## 📦 Установка
+
+```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: контекст сообщения (содержит информацию о сообщении, отправителе, чате и т.д.)
+//   - db: ваш пользовательский контекст базы данных (здесь мы используем NoDB — заглушку)
+func echo(ctx *laniakea.MsgContext, db laniakea.NoDB) error {
+	// Отвечаем пользователю текстом, который он прислал, без префикса команды.
+	// ctx.Text содержит сообщение пользователя, из которого удалена часть с командой.
+	ctx.Answer(ctx.Text) // Ввод пользователя БЕЗ команды
+	return nil
+}
+
+func main() {
+	// 1. Создаём опции бота. Замените "TOKEN" на реальный токен от @BotFather.
+	opts := &laniakea.BotOpts{Token: "TOKEN"}
+
+	// 2. Инициализируем новый экземпляр бота.
+	//    Используем laniakea.NoDB как тип контекста базы данных (база не нужна для примера).
+	bot, err := laniakea.NewBot[laniakea.NoDB](opts)
+	if err != nil {
+		log.Fatal(err)
+	}
+	// Гарантируем освобождение ресурсов бота при выходе.
+	defer bot.Close()
+
+	// 3. Создаём новый плагин с именем "ping".
+	//    Плагины помогают группировать связанные команды и промежуточные обработчики.
+	p := laniakea.NewPlugin[laniakea.NoDB]("ping")
+
+	// 4. Добавляем команду в плагин.
+	//    p.NewCommand(echo, "echo") создаёт команду, которая вызывает функцию 'echo' по команде "/echo".
+	p.AddCommand(p.NewCommand(echo, "echo"))
+
+	// 5. Добавляем ещё одну команду, используя анонимную функцию (замыкание).
+	//    Эта команда просто отвечает "Pong", когда пользователь отправляет "/ping".
+	p.AddCommand(p.NewCommand(func(ctx *laniakea.MsgContext, db laniakea.NoDB) error {
+		ctx.Answer("Pong")
+		return nil
+	}, "ping"))
+
+	// 6. Настраиваем бота: задаём шаблон ошибки и добавляем плагин.
+	//    ErrorTemplate устанавливает формат для сообщений об ошибках (где %s будет заменён на текст ошибки).
+	//    AddPlugins(p) регистрирует наш плагин "ping" в боте.
+	bot = bot.ErrorTemplate("Ошибка\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.NoDB, если он не нужен.
+3. `NewPlugin`: Создаёт логическую группу для команд и Middleware.
+4. `AddCommand`: Регистрирует команду. Первый аргумент — функция-обработчик (`func(*MsgContext, T) error`), второй — имя команды (без слеша).
+5. **Функции-обработчики**: Получают *MsgContext (детали сообщения, методы типа Answer) и ваш контекст базы данных T, а ошибку возвращают для централизованной обработки.
+6. `ErrorTemplate`: Устанавливает шаблон для сообщений об ошибках. Плейсхолдер %s заменяется на текст ошибки.
+7. `AutoGenerateCommands`: Регистрирует команды из плагинов в Telegram для поддерживаемых scope.
+8. `Run()`: Запускает цикл опроса обновлений бота и возвращает ошибку, если старт или polling завершился неуспешно.
+9. Экземпляр `Bot` одноразовый. После завершения `Run()` или `RunWithContext()` для следующего запуска создавайте новый бот.
+
+## 📖 Основные концепции
+### Плагины (Plugins)
+Плагины — основной способ организации кода. Плагин может содержать несколько команд и Middleware.
+
+```go
+plugin := laniakea.NewPlugin[*MyDB]("admin")
+plugin.AddCommand(plugin.NewCommand(banUser, "ban"))
+bot.AddPlugins(plugin)
+```
+
+### Команды (Commands)
+Команда — это функция, которая обрабатывает конкретную команду бота (например, /start).
+
+```go
+func myHandler(ctx *laniakea.MsgContext, db *MyDB) error {
+    // Доступ к аргументам команды через ctx.Args ([]string)
+    // Ответ пользователю: ctx.Answer("какой-то текст")
+    return nil
+}
+```
+
+### Контекст сообщения (MsgContext)
+Предоставляет доступ к входящему сообщению и полезные методы для ответа:
+
+- `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)`: Редактирует сообщение с `parse_mode` none после нажатия inline-кнопки.
+- `EditCallbackMarkdown(text string)`: Редактирует сообщение в формате MarkdownV2 (экранирование на вашей стороне) после нажатия inline-кнопки.
+- `SendAction(action tgapi.ChatActionType)`: Отправляет действие "печатает", "загружает фото" и т.д.
+- Поля: `Text`, `Args`, `From`, `FromID`, `Msg`, `InlineMsgId`, `CallbackQueryId` и другие.
+- И много других методов и полей!
+
+### Контекст базы данных (Database Context)
+Параметр типа `T` в `NewBot[T]` — мощная функция. Вы можете передать любой тип, но для разделяемых зависимостей вроде пула соединений с БД обычно стоит использовать pointer type.
+
+```go
+type MyDB struct { /* ... */ }
+db := &MyDB{...}
+bot, err := laniakea.NewBot[*MyDB](opts)
+if err != nil {
+    log.Fatal(err)
+}
+bot.DatabaseContext(db)
+```
+
+### Сцены и сессии (Scenes and Sessions)
+
+Сцены описывают многошаговые диалоги внутри плагина. Активная сцена хранится в session state, ключ которого зависит от scope, поэтому поток можно изолировать на пользователя, на чат или на пару пользователь-чат.
+
+```go
+plugin := laniakea.NewPlugin[MyDB]("signup")
+
+plugin.NewScene("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` в зависимости от того, насколько широко должен разделяться диалог.
+
+### 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 *MsgContext, 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.AddCommand(plugin.NewCommand(banUser, "ban"))
+```
+
+### Примеры middleware
+
+1. Логирующий middleware – логирует каждое выполнение команды.
+```go
+func loggingMiddleware(ctx *laniakea.MsgContext, db *MyDB) bool {
+    log.Printf("Пользователь %d выполнил команду: %s", ctx.FromID, ctx.Msg.Text)
+    return true // продолжаем к следующему middleware/команде
+}
+```
+
+2. Middleware только для администраторов – ограничивает доступ пользователям с определённой ролью.
+```go
+func adminOnlyMiddleware(ctx *laniakea.MsgContext, db *MyDB) bool {
+    if !db.IsAdmin(ctx.FromID) { // предполагается, что db имеет метод IsAdmin
+        ctx.Answer("⛔ Доступ запрещён. Только для администраторов.")
+        return false // останавливаем выполнение
+    }
+    return true
+}
+```
+
+### Важные замечания
+- Middleware может изменять MsgContext (например, добавлять пользовательские поля) перед запуском команды.
+
+## ⚙️ Расширенная настройка
+- **Инлайн-клавиатуры**: Создавайте клавиатуры с помощью `laniakea.NewInlineKeyboardJson`, `laniakea.NewInlineKeyboardBase64` или `laniakea.NewInlineKeyboard`. `Bot.SetPayloadType(...)` задаёт payload format по умолчанию, а `InlineKeyboard.SetPayloadType(...)` переопределяет его для конкретной клавиатуры.
+- **Ограничение запросов**: Передайте настроенный `utils.RateLimiter` через `BotOpts` для корректной обработки лимитов Telegram.
+- **Локализация**: `L10n` безопасен для конкурентного использования после подключения к боту.
+- **Пользовательские update handlers**: Используйте `plugin.AddUpdateHandler(...)` для Telegram update types вне command/payload flow.
+- **Жизненный цикл**: `RunWithContext(...)` не вызывает `Close()` автоматически. Завершайте бот явно и создавайте новый `Bot` для следующего запуска.
+
+## Обработка 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,23 @@
+# 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:
+
+- `Priority 1`: update schema contract, user-facing vs internal error model, configuration freeze model.
+- `Priority 2`: webhook runtime model, authorization and policy model, observability model.
+- `Priority 3`: service layer and dependency graph model, plugin composition contract.
+
+Completed former high-priority items:
+
+- `1. Conversation / Scene Model`: completed in `v1.0.0-rc.12`.
+- `2. Typed Handler Input Model`: completed in `v1.0.0-rc.12`.
+- `3. Request Context / Cancellation Model`: completed in `v1.0.0-rc.12`.

api.go

@@ -1,99 +0,0 @@
-package laniakea
-
-import (
-	"bytes"
-	"encoding/json"
-	"fmt"
-	"io"
-	"net/http"
-	"strings"
-
-	"git.nix13.pw/scuroneko/slog"
-)
-
-type Api struct {
-	token  string
-	logger *slog.Logger
-}
-
-func NewAPI(token string) *Api {
-	l := slog.CreateLogger().Level(GetLoggerLevel()).Prefix("API")
-	l.AddWriter(l.CreateJsonStdoutWriter())
-	return &Api{
-		token:  token,
-		logger: l,
-	}
-}
-func (api *Api) CloseApi() {
-	api.logger.Close()
-}
-
-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"`
-}
-
-type TelegramRequest[R, P any] struct {
-	method string
-	params P
-}
-
-func NewRequest[R, P any](method string, params P) TelegramRequest[R, P] {
-	return TelegramRequest[R, P]{method: method, params: params}
-}
-func (r TelegramRequest[R, P]) Do(api *Api) (*R, error) {
-	var buf bytes.Buffer
-	err := json.NewEncoder(&buf).Encode(r.params)
-	if err != nil {
-		return nil, err
-	}
-
-	if api.logger != nil {
-		api.logger.Debugln(strings.ReplaceAll(fmt.Sprintf(
-			"POST https://api.telegram.org/bot%s/%s %s",
-			"<TOKEN>", r.method, buf.String(),
-		), "\n", ""))
-	}
-
-	req, err := http.Post(fmt.Sprintf("https://api.telegram.org/bot%s/%s", api.token, r.method), "application/json", &buf)
-	if err != nil {
-		return nil, err
-	}
-	defer req.Body.Close()
-	data, err := io.ReadAll(req.Body)
-	if err != nil {
-		return nil, err
-	}
-
-	if api.logger != nil {
-		api.logger.Debugln(fmt.Sprintf("RES %s %s", r.method, string(data)))
-	}
-
-	response := new(ApiResponse[R])
-	err = json.Unmarshal(data, &response)
-	if err != nil {
-		return nil, err
-	}
-
-	if !response.Ok {
-		return nil, fmt.Errorf("[%d] %s", response.ErrorCode, response.Description)
-	}
-	return &response.Result, nil
-}
-
-func (b *Bot) GetFileByLink(link string) ([]byte, error) {
-	c := http.DefaultClient
-	u := fmt.Sprintf("https://api.telegram.org/file/bot%s/%s", b.token, link)
-	req, err := http.NewRequest("GET", u, nil)
-	if err != nil {
-		return nil, err
-	}
-	res, err := c.Do(req)
-	if err != nil {
-		return nil, err
-	}
-	defer res.Body.Close()
-	return io.ReadAll(res.Body)
-}

bot_opts.go

@@ -0,0 +1,271 @@
+package laniakea
+
+import (
+	"os"
+	"strconv"
+	"strings"
+
+	"git.scuroneko.dev/scuroneko/laniakea/tgapi"
+)
+
+// 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
+
+	// DropRLOverflow drops incoming updates when rate limit is exceeded instead of queuing.
+	// Use this to prioritize responsiveness over reliability.
+	DropRLOverflow 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
+}
+
+// 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)
+//
+// Returns a populated BotOpts.
+// NewBot validates required fields and returns ErrTokenRequired when TG_TOKEN is missing.
+func LoadOptsFromEnv() *BotOpts {
+	rateLimit := 30
+	maxWorkers := 32
+
+	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(os.Getenv("MAX_WORKERS")); err == nil {
+			maxWorkers = 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,
+		DropRLOverflow:    os.Getenv("DROP_RL_OVERFLOW") == "true",
+		StrictPayloadType: os.Getenv("STRICT_PAYLOAD_TYPE") == "true",
+
+		MaxWorkers: maxWorkers,
+	}
+}
+
+// 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
+}
+
+// SetDropRLOverflow drops incoming updates when rate limit is exceeded instead of queuing.
+// Use this to prioritize responsiveness over reliability. Default is false.
+func (opts *BotOpts) SetDropRLOverflow(drop bool) *BotOpts {
+	opts.DropRLOverflow = 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
+}
+
+// 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_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_scene.go

@@ -0,0 +1,59 @@
+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 *MsgContext) (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
+}
+
+func (bot *Bot[T]) buildSceneKey(scope SceneScope, ctx *MsgContext) (string, bool) {
+	return buildSceneKey(scope, ctx)
+}

bot_test.go

@@ -0,0 +1,217 @@
+package laniakea
+
+import (
+	"context"
+	"errors"
+	"path/filepath"
+	"reflect"
+	"testing"
+	"time"
+
+	"git.scuroneko.dev/scuroneko/laniakea/tgapi"
+	"git.scuroneko.dev/scuroneko/slog"
+)
+
+func TestGetUpdateTypesReturnsCopy(t *testing.T) {
+	bot := &Bot[NoDB]{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[NoDB]{logger: slog.CreateLogger()}
+	plugin := NewPlugin[NoDB]("demo")
+
+	cmd := plugin.NewCommand(func(ctx *MsgContext, db NoDB) error { return nil }, "start")
+	plugin.AddMiddleware(NewMiddleware("base", func(ctx *MsgContext, db NoDB) bool { return true }))
+
+	bot.AddPlugins(plugin)
+
+	cmd.SetDescription("mutated after registration")
+	plugin.NewCommand(func(ctx *MsgContext, db NoDB) error { return nil }, "late")
+	plugin.AddMiddleware(NewMiddleware("late", func(ctx *MsgContext, db NoDB) 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[NoDB]{payloadType: BotPayloadBase64}
+
+	if got := bot.GetPayloadType(); got != BotPayloadBase64 {
+		t.Fatalf("unexpected initial payload type: %q", got)
+	}
+	bot.SetPayloadType(BotPayloadJson)
+	if got := bot.GetPayloadType(); got != BotPayloadJson {
+		t.Fatalf("unexpected updated payload type: %q", got)
+	}
+	bot.SetStrictPayloadType(true)
+	if !bot.strictPayloadType {
+		t.Fatal("expected strict payload type to be enabled")
+	}
+}
+
+func TestAddPluginsSkipsNilPlugin(t *testing.T) {
+	bot := &Bot[NoDB]{logger: slog.CreateLogger()}
+	plugin := NewPlugin[NoDB]("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[NoDB]{}
+
+	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 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 TestAddDatabaseLoggerWriterSkipsWhenDBContextIsUnset(t *testing.T) {
+	bot := &Bot[NoDB]{logger: slog.CreateLogger()}
+	called := false
+
+	bot.AddDatabaseLoggerWriter(func(db NoDB) slog.LoggerWriter {
+		called = true
+		return nil
+	})
+
+	if called {
+		t.Fatal("expected database logger writer to be skipped when db context is unset")
+	}
+}
+
+func TestAddDatabaseLoggerWriterSkipsWhenDBContextIsNil(t *testing.T) {
+	type testDB struct{}
+
+	bot := &Bot[*testDB]{logger: slog.CreateLogger()}
+	var db *testDB
+	bot.DatabaseContext(db)
+
+	called := false
+	bot.AddDatabaseLoggerWriter(func(db *testDB) slog.LoggerWriter {
+		called = true
+		return nil
+	})
+
+	if called {
+		t.Fatal("expected database logger writer to be skipped when db context is nil")
+	}
+}
+
+func TestShouldWarnOnValueDBContext(t *testing.T) {
+	type testDB struct{}
+	type dbIface interface{ Ping() error }
+
+	tests := []struct {
+		name string
+		got  bool
+		want bool
+	}{
+		{name: "NoDB", got: shouldWarnOnValueDBContext[NoDB](), want: false},
+		{name: "pointer", got: shouldWarnOnValueDBContext[*testDB](), want: false},
+		{name: "interface", got: shouldWarnOnValueDBContext[dbIface](), want: false},
+		{name: "map", got: shouldWarnOnValueDBContext[map[string]int](), want: false},
+		{name: "struct", got: shouldWarnOnValueDBContext[testDB](), want: true},
+		{name: "int", got: shouldWarnOnValueDBContext[int](), want: true},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			if tt.got != tt.want {
+				t.Fatalf("shouldWarnOnValueDBContext = %v, want %v", tt.got, tt.want)
+			}
+		})
+	}
+}
+
+func TestDatabaseContextMarksValueWarningOnce(t *testing.T) {
+	type testDB struct{}
+
+	bot := &Bot[testDB]{logger: slog.CreateLogger()}
+	bot.DatabaseContext(testDB{})
+	if !bot.warnedValueDB {
+		t.Fatal("expected value-typed database context to mark warning state")
+	}
+
+	ptrBot := &Bot[*testDB]{logger: slog.CreateLogger()}
+	ptrBot.DatabaseContext(&testDB{})
+	if ptrBot.warnedValueDB {
+		t.Fatal("did not expect pointer-typed database context to mark warning state")
+	}
+}
+
+func TestRunWithContextRejectsSecondRun(t *testing.T) {
+	ctx, cancel := context.WithCancel(context.Background())
+	cancel()
+
+	bot := &Bot[NoDB]{
+		logger:      slog.CreateLogger(),
+		prefixes:    []string{"/"},
+		plugins:     []Plugin[NoDB]{{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)
+	}
+}

cmd_generator.go

@@ -0,0 +1,175 @@
+package laniakea
+
+import (
+	"errors"
+	"fmt"
+	"regexp"
+	"sort"
+	"strings"
+
+	"git.scuroneko.dev/scuroneko/laniakea/tgapi"
+)
+
+// CmdRegexp matches command names allowed for Telegram command registration.
+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")
+
+// Internal helper to build a BotCommand description with generated usage text.
+func generateBotCommand[T any](cmd *Command[T]) tgapi.BotCommand {
+	desc := ""
+	if len(cmd.description) > 0 {
+		desc = cmd.description
+	}
+
+	var descArgs []string
+	for _, a := range cmd.args {
+		if a.required {
+			descArgs = append(descArgs, fmt.Sprintf("<%s>", a.text))
+		} else {
+			descArgs = append(descArgs, fmt.Sprintf("[%s]", a.text))
+		}
+	}
+
+	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}
+	}
+	return tgapi.BotCommand{Command: cmd.command, Description: usage}
+}
+
+// Internal helper to validate Telegram command names.
+func checkCmdRegex(cmd string) bool { return CmdRegexp.MatchString(cmd) }
+
+// Internal helper to collect non-skipped, valid commands from one plugin.
+func gatherCommandsForPlugin[T any](pl Plugin[T]) []tgapi.BotCommand {
+	commands := make([]tgapi.BotCommand, 0)
+	names := make([]string, 0, len(pl.commands))
+	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
+}
+
+// Internal helper to collect all auto-generated commands from registered plugins.
+func gatherCommands[T any](bot *Bot[T]) []tgapi.BotCommand {
+	commands := make([]tgapi.BotCommand, 0)
+	for _, pl := range bot.plugins {
+		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 registers all plugin-defined commands with Telegram's Bot API
+// across three scopes:
+//   - Private chats (users)
+//   - Group chats
+//   - Group administrators
+//
+// It first deletes existing commands to ensure a clean state, then sets the new
+// set of commands for all scopes. This ensures consistency even if commands were
+// previously modified manually via @BotFather.
+//
+// Returns ErrTooManyCommands if the total number of commands exceeds 100.
+// Returns any API error from Telegram (e.g., network issues, invalid scope).
+//
+// Important: This method assumes the bot has been properly initialized and
+// the API client is authenticated and ready.
+//
+// Usage:
+//
+//	err := bot.AutoGenerateCommands()
+//	if err != nil {
+//	    log.Fatal(err)
+//	}
+func (bot *Bot[T]) AutoGenerateCommands() error {
+	commands := gatherCommands(bot)
+	if len(commands) > 100 {
+		return ErrTooManyCommands
+	}
+
+	// Clear existing commands to avoid duplication or stale entries
+	_, err := bot.api.DeleteMyCommands(tgapi.DeleteMyCommandsP{})
+	if err != nil {
+		return fmt.Errorf("failed to delete existing commands: %w", err)
+	}
+
+	// Register commands for each scope
+	scopes := []*tgapi.BotCommandScope{
+		{Type: tgapi.BotCommandScopePrivateType},
+		{Type: tgapi.BotCommandScopeGroupType},
+		{Type: tgapi.BotCommandScopeAllChatAdministratorsType},
+	}
+
+	for _, scope := range scopes {
+		_, err = bot.api.SetMyCommands(tgapi.SetMyCommandsP{
+			Commands: commands,
+			Scope:    scope,
+		})
+		if err != nil {
+			return fmt.Errorf("failed to set commands for scope %q: %w", scope.Type, err)
+		}
+	}
+
+	return nil
+}
+
+// AutoGenerateCommandsForScope registers all plugin-defined commands with Telegram's Bot API
+// for the specified command scope. It first deletes any existing commands in that scope
+// to ensure a clean state, then sets the new set of commands.
+//
+// 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 {
+	commands := gatherCommands(bot)
+	if len(commands) > 100 {
+		return ErrTooManyCommands
+	}
+
+	_, err := bot.api.DeleteMyCommands(tgapi.DeleteMyCommandsP{Scope: scope})
+	if err != nil {
+		return fmt.Errorf("failed to delete existing commands: %w", err)
+	}
+
+	_, err = bot.api.SetMyCommands(tgapi.SetMyCommandsP{
+		Commands: commands,
+		Scope:    scope,
+	})
+	if err != nil {
+		return fmt.Errorf("failed to set commands for scope %q: %w", scope.Type, err)
+	}
+	return nil
+}

cmd_generator_test.go

@@ -0,0 +1,85 @@
+package laniakea
+
+import (
+	"errors"
+	"io"
+	"net/http"
+	"reflect"
+	"strconv"
+	"strings"
+	"sync/atomic"
+	"testing"
+
+	"git.scuroneko.dev/scuroneko/laniakea/tgapi"
+	"git.scuroneko.dev/scuroneko/slog"
+)
+
+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[NoDB]("overflow")
+	exec := func(ctx *MsgContext, db NoDB) error { return nil }
+	for i := 0; i < 101; i++ {
+		plugin.AddCommand(NewCommand(exec, "cmd"+strconv.Itoa(i)))
+	}
+
+	bot := &Bot[NoDB]{
+		api:     api,
+		logger:  slog.CreateLogger(),
+		plugins: []Plugin[NoDB]{*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[NoDB]("sorted")
+	exec := func(ctx *MsgContext, db NoDB) error { return nil }
+
+	plugin.AddCommand(NewCommand(exec, "zeta"))
+	plugin.AddCommand(NewCommand(exec, "alpha"))
+	plugin.AddCommand(NewCommand(exec, "mid"))
+
+	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)
+	}
+}

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.
+  - MsgContext 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.DBContext](laniakea.LoadOptsFromEnv())
+	if err != nil {
+	    return err
+	}
+	bot.DatabaseContext(myDB).
+	    AddUpdateType(tgapi.UpdateTypeMessage).
+	    AddPrefixes("/", "!").
+	    AddPlugins(&startPlugin, &helpPlugin).
+	    AddMiddleware(authMiddleware, logMiddleware).
+	    AddRunner(cleanupRunner).
+	    AddL10n(l10n.New())
+
+	return bot.Run()
+
+Configure bots, plugins, and localization before starting Run or RunWithContext.
+Runtime accessors are safe for concurrent use unless stated otherwise.
+*/
+package laniakea

drafts.go

@@ -0,0 +1,262 @@
+package laniakea
+
+import (
+	"math/rand/v2"
+	"sync"
+	"sync/atomic"
+
+	"git.scuroneko.dev/scuroneko/laniakea/tgapi"
+)
+
+// Interface for generating unique draft IDs.
+type draftIdGenerator interface {
+	// Next returns the next unique draft ID.
+	Next() uint64
+}
+
+// RandomDraftIdGenerator generates draft IDs using cryptographically secure random numbers.
+// Suitable for distributed systems or when ID predictability is undesirable.
+type RandomDraftIdGenerator struct{}
+
+// Next returns a random 64-bit unsigned integer.
+func (g *RandomDraftIdGenerator) Next() uint64 {
+	return rand.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 cryptographically secure random numbers for draft IDs.
+// All drafts created via this provider will have unpredictable, unique IDs.
+func NewRandomDraftProvider(api *tgapi.API) *DraftProvider {
+	return &DraftProvider{
+		api: api, generator: &RandomDraftIdGenerator{},
+		drafts: make(map[uint64]*Draft),
+	}
+}
+
+// NewLinearDraftProvider creates a new DraftProvider using linear (incrementing) draft IDs.
+//
+// startValue is the initial value for the counter. Use 0 for fresh start, or a known
+// value to resume from persisted state.
+//
+// This is useful when you need to store draft IDs externally (e.g., in a database)
+// and want to reconstruct drafts after restart.
+func NewLinearDraftProvider(api *tgapi.API, startValue uint64) *DraftProvider {
+	g := &LinearDraftIdGenerator{}
+	g.lastId.Store(startValue)
+	return &DraftProvider{
+		api:       api,
+		generator: g,
+		drafts:    make(map[uint64]*Draft),
+	}
+}
+
+// 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 {
+	id := p.generator.Next()
+	draft := &Draft{
+		api:       p.api,
+		provider:  p,
+		parseMode: parseMode,
+		ID:        id,
+		Message:   "",
+	}
+	p.mu.Lock()
+	p.drafts[id] = draft
+	p.mu.Unlock()
+	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.
+//
+// Entities are stored by reference. If you plan to mutate the slice later,
+// pass a copy: `SetEntities(append([]tgapi.MessageEntity{}, myEntities...))`.
+func (d *Draft) SetEntities(entities []tgapi.MessageEntity) *Draft {
+	d.entities = entities
+	return d
+}
+
+// Push appends text to the draft and attempts to update the server-side draft.
+//
+// Returns an error if the Telegram API rejects the update (e.g., due to network issues).
+// The draft's Message field is always updated, even if the API call fails.
+//
+// Use this method to build the message incrementally.
+func (d *Draft) Push(text string) error {
+	return d.push(text)
+}
+
+// GetMessage returns the current content of the draft.
+//
+// Useful for inspection, logging, or validation before flushing.
+func (d *Draft) GetMessage() string {
+	return d.Message
+}
+
+// Clear resets the draft's message content to empty string.
+//
+// Does not affect server-side draft — use Flush() for that.
+func (d *Draft) Clear() {
+	d.Message = ""
+}
+
+// Delete removes the draft from its provider and clears its content.
+//
+// This is an internal method used by Flush(). You may call it manually if you
+// want to cancel a draft without sending it.
+func (d *Draft) Delete() {
+	if d.provider != nil {
+		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
+	}
+
+	params := tgapi.SendMessageP{
+		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
+}
+
+// Internal helper for Push that updates the server-side draft.
+func (d *Draft) push(text string) error {
+	if d.chatID == 0 {
+		return ErrDraftChatIDZero
+	}
+	d.Message += text
+	if err := validateMessageText(d.Message); err != nil {
+		return err
+	}
+	params := tgapi.SendMessageDraftP{
+		ChatID:    d.chatID,
+		DraftID:   d.ID,
+		Text:      d.Message,
+		ParseMode: d.parseMode,
+		Entities:  d.entities,
+	}
+	if d.messageThreadID > 0 {
+		params.MessageThreadID = d.messageThreadID
+	}
+	_, err := d.api.SendMessageDraft(params)
+	return err
+}

drafts_test.go

@@ -0,0 +1,55 @@
+package laniakea
+
+import (
+	"errors"
+	"strings"
+	"testing"
+
+	"git.scuroneko.dev/scuroneko/laniakea/tgapi"
+	"git.scuroneko.dev/scuroneko/slog"
+)
+
+func TestDraftFlushRequiresChatID(t *testing.T) {
+	draft := NewRandomDraftProvider(&tgapi.API{}).NewDraft(tgapi.ParseNone)
+	draft.Message = "hello"
+
+	if err := draft.Flush(); err != ErrDraftChatIDZero {
+		t.Fatalf("expected ErrDraftChatIDZero, got %v", err)
+	}
+}
+
+func TestMsgContextNewDraftWorksWithoutLimiter(t *testing.T) {
+	ctx := &MsgContext{
+		Api: &tgapi.API{},
+		Msg: &tgapi.Message{
+			Chat: &tgapi.Chat{ID: 42, Type: string(tgapi.ChatTypePrivate)},
+		},
+		Logger:        slog.CreateLogger(),
+		draftProvider: NewRandomDraftProvider(&tgapi.API{}),
+	}
+
+	draft := ctx.NewDraft()
+	if draft == nil {
+		t.Fatal("expected draft")
+	}
+	if draft.chatID != 42 {
+		t.Fatalf("unexpected chat id: %d", draft.chatID)
+	}
+}
+
+func TestDraftFlushRejectsLongMessage(t *testing.T) {
+	draft := NewRandomDraftProvider(&tgapi.API{}).NewDraft(tgapi.ParseNone).SetChat(42, 0)
+	draft.Message = strings.Repeat("a", maxMessageTextLen+1)
+
+	if err := draft.Flush(); !errors.Is(err, ErrMessageTooLong) {
+		t.Fatalf("expected ErrMessageTooLong, got %v", err)
+	}
+}
+
+func TestDraftPushRejectsLongMessage(t *testing.T) {
+	draft := NewRandomDraftProvider(&tgapi.API{}).NewDraft(tgapi.ParseNone).SetChat(42, 0)
+
+	if err := draft.Push(strings.Repeat("a", maxMessageTextLen+1)); !errors.Is(err, ErrMessageTooLong) {
+		t.Fatalf("expected ErrMessageTooLong, got %v", err)
+	}
+}

errors.go

@@ -0,0 +1,81 @@
+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")
+	// 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")
+)
+
+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,29 +1,19 @@
-module git.nix13.pw/scuroneko/laniakea
+module git.scuroneko.dev/scuroneko/laniakea
 
-go 1.25.6
+go 1.26
+
+retract v1.0.0-rc.5
 
 require (
-	git.nix13.pw/scuroneko/extypes v1.0.2
-	git.nix13.pw/scuroneko/slog v1.0.2
-	github.com/redis/go-redis/v9 v9.17.3
-	github.com/vinovest/sqlx v1.7.1
-	go.mongodb.org/mongo-driver/v2 v2.5.0
+	git.scuroneko.dev/scuroneko/extypes v1.2.3
+	git.scuroneko.dev/scuroneko/slog v1.1.3
+	github.com/alitto/pond/v2 v2.7.0
+	golang.org/x/time v0.15.0
 )
 
 require (
-	github.com/cespare/xxhash/v2 v2.3.0 // indirect
-	github.com/dgryski/go-rendezvous v0.0.0-20200823014737-9f7001d12a5f // indirect
 	github.com/fatih/color v1.18.0 // indirect
-	github.com/klauspost/compress v1.18.3 // indirect
 	github.com/mattn/go-colorable v0.1.14 // indirect
 	github.com/mattn/go-isatty v0.0.20 // indirect
-	github.com/muir/sqltoken v0.2.1 // indirect
-	github.com/xdg-go/pbkdf2 v1.0.0 // indirect
-	github.com/xdg-go/scram v1.2.0 // indirect
-	github.com/xdg-go/stringprep v1.0.4 // indirect
-	github.com/youmark/pkcs8 v0.0.0-20240726163527-a2c0da244d78 // indirect
-	golang.org/x/crypto v0.47.0 // indirect
-	golang.org/x/sync v0.19.0 // indirect
-	golang.org/x/sys v0.40.0 // indirect
-	golang.org/x/text v0.33.0 // indirect
+	golang.org/x/sys v0.42.0 // indirect
 )

go.sum

@@ -1,87 +1,17 @@
-filippo.io/edwards25519 v1.1.0 h1:FNf4tywRC1HmFuKW5xopWpigGjJKiJSV0Cqo0cJWDaA=
-filippo.io/edwards25519 v1.1.0/go.mod h1:BxyFTGdWcka3PhytdK4V28tE5sGfRvvvRV7EaN4VDT4=
-git.nix13.pw/scuroneko/extypes v1.0.2 h1:Qz1InLccaB9crXY33oGrSetPHePKfQAUqW/p/iYXmJk=
-git.nix13.pw/scuroneko/extypes v1.0.2/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/bsm/ginkgo/v2 v2.12.0 h1:Ny8MWAHyOepLGlLKYmXG4IEkioBysk6GpaRTLC8zwWs=
-github.com/bsm/ginkgo/v2 v2.12.0/go.mod h1:SwYbGRRDovPVboqFv0tPTcG1sN61LM1Z4ARdbAV9g4c=
-github.com/bsm/gomega v1.27.10 h1:yeMWxP2pV2fG3FgAODIY8EiRE3dy0aeFYt4l7wh6yKA=
-github.com/bsm/gomega v1.27.10/go.mod h1:JyEr/xRbxbtgWNi8tIEVPUYZ5Dzef52k01W3YH0H+O0=
-github.com/cespare/xxhash/v2 v2.3.0 h1:UL815xU9SqsFlibzuggzjXhog7bL6oX9BbNZnL2UFvs=
-github.com/cespare/xxhash/v2 v2.3.0/go.mod h1:VGX0DQ3Q6kWi7AoAeZDth3/j3BFtOZR5XLFGgcrjCOs=
-github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
-github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
-github.com/dgryski/go-rendezvous v0.0.0-20200823014737-9f7001d12a5f h1:lO4WD4F/rVNCu3HqELle0jiPLLBs70cWOduZpkS1E78=
-github.com/dgryski/go-rendezvous v0.0.0-20200823014737-9f7001d12a5f/go.mod h1:cuUVRXasLTGF7a8hSLbxyZXjz+1KgoB3wDUb6vlszIc=
+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/slog v1.1.3 h1:vI4GZykn8gDb6OJ2xq+KLcEk38M7O4e/z1kzpeRHEHw=
+git.scuroneko.dev/scuroneko/slog v1.1.3/go.mod h1:gnDap54sfZv3EuSyZd7fjOH46aLbDFpvtN2wgFcWkgE=
+github.com/alitto/pond/v2 v2.7.0 h1:c76L+yN916m/DRXjGCeUBHHu92uWnh/g1bwVk4zyyXg=
+github.com/alitto/pond/v2 v2.7.0/go.mod h1:xkjYEgQ05RSpWdfSd1nM3OVv7TBhLdy7rMp3+2Nq+yE=
 github.com/fatih/color v1.18.0 h1:S8gINlzdQ840/4pfAwic/ZE0djQEH3wM94VfqLTZcOM=
 github.com/fatih/color v1.18.0/go.mod h1:4FelSpRwEGDpQ12mAdzqdOukCy4u8WUtOY6lkT/6HfU=
-github.com/go-sql-driver/mysql v1.9.0 h1:Y0zIbQXhQKmQgTp44Y1dp3wTXcn804QoTptLZT1vtvo=
-github.com/go-sql-driver/mysql v1.9.0/go.mod h1:pDetrLJeA3oMujJuvXc8RJoasr589B6A9fwzD3QMrqw=
-github.com/google/go-cmp v0.6.0 h1:ofyhxvXcZhMsU5ulbFiLKl/XBFqE1GSq7atu8tAmTRI=
-github.com/google/go-cmp v0.6.0/go.mod h1:17dUlkBOakJ0+DkrSSNjCkIjxS6bF9zb3elmeNGIjoY=
-github.com/klauspost/compress v1.18.3 h1:9PJRvfbmTabkOX8moIpXPbMMbYN60bWImDDU7L+/6zw=
-github.com/klauspost/compress v1.18.3/go.mod h1:R0h/fSBs8DE4ENlcrlib3PsXS61voFxhIs2DeRhCvJ4=
-github.com/lib/pq v1.10.9 h1:YXG7RB+JIjhP29X+OtkiDnYaXQwpS4JEWq7dtCCRUEw=
-github.com/lib/pq v1.10.9/go.mod h1:AlVN5x4E4T544tWzH6hKfbfQvm3HdbOxrmggDNAPY9o=
 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=
-github.com/mattn/go-sqlite3 v1.14.16 h1:yOQRA0RpS5PFz/oikGwBEqvAWhWg5ufRz4ETLjwpU1Y=
-github.com/mattn/go-sqlite3 v1.14.16/go.mod h1:2eHXhiwb8IkHr+BDWZGa96P6+rkvnG63S2DGjv9HUNg=
-github.com/muir/sqltoken v0.2.1 h1:19KvJrCj9aOMfU921hjnizWPlQmPTe+tb36zupOY2FA=
-github.com/muir/sqltoken v0.2.1/go.mod h1:sSlj5M0VqQ4OuedmxwWs1TmzzRXaH3DLf5ukzg6meIo=
-github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
-github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
-github.com/redis/go-redis/v9 v9.17.3 h1:fN29NdNrE17KttK5Ndf20buqfDZwGNgoUr9qjl1DQx4=
-github.com/redis/go-redis/v9 v9.17.3/go.mod h1:u410H11HMLoB+TP67dz8rL9s6QW2j76l0//kSOd3370=
-github.com/stretchr/testify v1.11.1 h1:7s2iGBzp5EwR7/aIZr8ao5+dra3wiQyKjjFuvgVKu7U=
-github.com/stretchr/testify v1.11.1/go.mod h1:wZwfW3scLgRK+23gO65QZefKpKQRnfz6sD981Nm4B6U=
-github.com/vinovest/sqlx v1.7.1 h1:kdq4v0N9kRLpytWGSWOw4aulOGdQPmIoMR6Y+cTBxow=
-github.com/vinovest/sqlx v1.7.1/go.mod h1:3fAv74r4iDMv2PpFomADb+vex5ukzfYn4GseC9KngD8=
-github.com/xdg-go/pbkdf2 v1.0.0 h1:Su7DPu48wXMwC3bs7MCNG+z4FhcyEuz5dlvchbq0B0c=
-github.com/xdg-go/pbkdf2 v1.0.0/go.mod h1:jrpuAogTd400dnrH08LKmI/xc1MbPOebTwRqcT5RDeI=
-github.com/xdg-go/scram v1.2.0 h1:bYKF2AEwG5rqd1BumT4gAnvwU/M9nBp2pTSxeZw7Wvs=
-github.com/xdg-go/scram v1.2.0/go.mod h1:3dlrS0iBaWKYVt2ZfA4cj48umJZ+cAEbR6/SjLA88I8=
-github.com/xdg-go/stringprep v1.0.4 h1:XLI/Ng3O1Atzq0oBs3TWm+5ZVgkq2aqdlvP9JtoZ6c8=
-github.com/xdg-go/stringprep v1.0.4/go.mod h1:mPGuuIYwz7CmR2bT9j4GbQqutWS1zV24gijq1dTyGkM=
-github.com/youmark/pkcs8 v0.0.0-20240726163527-a2c0da244d78 h1:ilQV1hzziu+LLM3zUTJ0trRztfwgjqKnBWNtSRkbmwM=
-github.com/youmark/pkcs8 v0.0.0-20240726163527-a2c0da244d78/go.mod h1:aL8wCCfTfSfmXjznFBSZNN13rSJjlIOI1fUNAtF7rmI=
-github.com/yuin/goldmark v1.4.13/go.mod h1:6yULJ656Px+3vBD8DxQVa3kxgyrAnzto9xy5taEt/CY=
-go.mongodb.org/mongo-driver/v2 v2.5.0 h1:yXUhImUjjAInNcpTcAlPHiT7bIXhshCTL3jVBkF3xaE=
-go.mongodb.org/mongo-driver/v2 v2.5.0/go.mod h1:yOI9kBsufol30iFsl1slpdq1I0eHPzybRWdyYUs8K/0=
-golang.org/x/crypto v0.0.0-20190308221718-c2843e01d9a2/go.mod h1:djNgcEr1/C05ACkg1iLfiJU5Ep61QUkGW8qpdssI0+w=
-golang.org/x/crypto v0.0.0-20210921155107-089bfa567519/go.mod h1:GvvjBRRGRdwPK5ydBHafDWAxML/pGHZbMvKqRZ5+Abc=
-golang.org/x/crypto v0.47.0 h1:V6e3FRj+n4dbpw86FJ8Fv7XVOql7TEwpHapKoMJ/GO8=
-golang.org/x/crypto v0.47.0/go.mod h1:ff3Y9VzzKbwSSEzWqJsJVBnWmRwRSHt/6Op5n9bQc4A=
-golang.org/x/mod v0.6.0-dev.0.20220419223038-86c51ed26bb4/go.mod h1:jJ57K6gSWd91VN4djpZkiMVwK6gcyfeH4XE8wZrZaV4=
-golang.org/x/net v0.0.0-20190620200207-3b0461eec859/go.mod h1:z5CRVTTTmAJ677TzLLGU+0bjPO0LkuOLi4/5GtJWs/s=
-golang.org/x/net v0.0.0-20210226172049-e18ecbb05110/go.mod h1:m0MpNAwzfU5UDzcl9v0D8zg8gWTRqZa9RBIspLL5mdg=
-golang.org/x/net v0.0.0-20220722155237-a158d28d115b/go.mod h1:XRhObCWvk6IyKnWLug+ECip1KBveYUHfp+8e9klMJ9c=
-golang.org/x/sync v0.0.0-20190423024810-112230192c58/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
-golang.org/x/sync v0.0.0-20220722155255-886fb9371eb4/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
-golang.org/x/sync v0.19.0 h1:vV+1eWNmZ5geRlYjzm2adRgW2/mcpevXNg50YZtPCE4=
-golang.org/x/sync v0.19.0/go.mod h1:9KTHXmSnoGruLpwFjVSX0lNNA75CykiMECbovNTZqGI=
-golang.org/x/sys v0.0.0-20190215142949-d0b11bdaac8a/go.mod h1:STP8DvDyc/dI5b8T5hshtkjS+E42TnysNCUPdjciGhY=
-golang.org/x/sys v0.0.0-20201119102817-f84b799fce68/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
-golang.org/x/sys v0.0.0-20210615035016-665e8c7367d1/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
-golang.org/x/sys v0.0.0-20220520151302-bc2c85ada10a/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
-golang.org/x/sys v0.0.0-20220722155257-8c9f86f7a55f/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
 golang.org/x/sys v0.6.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
-golang.org/x/sys v0.40.0 h1:DBZZqJ2Rkml6QMQsZywtnjnnGvHza6BTfYFWY9kjEWQ=
-golang.org/x/sys v0.40.0/go.mod h1:OgkHotnGiDImocRcuBABYBEXf8A9a87e/uXjp9XT3ks=
-golang.org/x/term v0.0.0-20201126162022-7de9c90e9dd1/go.mod h1:bj7SfCRtBDWHUb9snDiAeCFNEtKQo2Wmx5Cou7ajbmo=
-golang.org/x/term v0.0.0-20210927222741-03fcf44c2211/go.mod h1:jbD1KX2456YbFQfuXm/mYQcufACuNUgVhRMnK/tPxf8=
-golang.org/x/text v0.3.0/go.mod h1:NqM8EUOU14njkJ3fqMW+pc6Ldnwhi/IjpwHt7yyuwOQ=
-golang.org/x/text v0.3.3/go.mod h1:5Zoc/QRtKVWzQhOtBMvqHzDpF6irO9z98xDceosuGiQ=
-golang.org/x/text v0.3.7/go.mod h1:u+2+/6zg+i71rQMx5EYifcz6MCKuco9NR6JIITiCfzQ=
-golang.org/x/text v0.3.8/go.mod h1:E6s5w1FMmriuDzIBO73fBruAKo1PCIq6d2Q6DHfQ8WQ=
-golang.org/x/text v0.33.0 h1:B3njUFyqtHDUI5jMn1YIr5B0IE2U0qck04r6d4KPAxE=
-golang.org/x/text v0.33.0/go.mod h1:LuMebE6+rBincTi9+xWTY8TztLzKHc/9C1uBCG27+q8=
-golang.org/x/tools v0.0.0-20180917221912-90fa682c2a6e/go.mod h1:n7NCudcB/nEzxVGmLbDWY5pfWTLqBcC2KZ6jyYvM4mQ=
-golang.org/x/tools v0.0.0-20191119224855-298f0cb1881e/go.mod h1:b+2E5dAYhXwXZwtnZ6UAqBI28+e2cm9otk0dWdXHAEo=
-golang.org/x/tools v0.1.12/go.mod h1:hNGJHUnrk76NpqgfD5Aqm5Crs+Hm0VOH/i9J2+nxYbc=
-golang.org/x/xerrors v0.0.0-20190717185122-a985d3407aa7/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0=
-gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
-gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
+golang.org/x/sys v0.42.0 h1:omrd2nAlyT5ESRdCLYdm3+fMfNFE/+Rf4bDIQImRJeo=
+golang.org/x/sys v0.42.0/go.mod h1:4GL1E5IUh+htKOUEOaiffhrAeqysfVGipDYzABqnCmw=
+golang.org/x/time v0.15.0 h1:bbrp8t3bGUeFOx08pvsMYRTCVSMk89u4tKbNOZbp88U=
+golang.org/x/time v0.15.0/go.mod h1:Y4YMaQmXwGQZoFaVFk4YpCt4FLQMYKZe9oeV/f4MSno=

handler.go

@@ -1,99 +1,384 @@
 package laniakea
 
 import (
+	"context"
+	"encoding/base64"
 	"encoding/json"
+	"errors"
+	"fmt"
 	"strings"
+
+	"git.scuroneko.dev/scuroneko/laniakea/tgapi"
 )
 
-func (b *Bot) handleMessage(update *Update, ctx *MsgContext) {
-	if update.Message == nil {
+// ErrInvalidPayloadType is returned when callback payload encoding type is unknown.
+var ErrInvalidPayloadType = errors.New("invalid payload type")
+
+func (bot *Bot[T]) handle(parentCtx context.Context, u *tgapi.Update) {
+	defer func() {
+		if r := recover(); r != nil {
+			bot.logger.Errorln(fmt.Sprintf("panic in handle: %v", r))
+		}
+	}()
+
+	ctx, cancel := context.WithCancel(parentCtx)
+	defer cancel()
+
+	msgCtx := &MsgContext{
+		Update: *u, Api: bot.api,
+		Logger:        bot.logger,
+		errorTemplate: bot.errorTemplate,
+		l10n:          bot.l10n,
+		draftProvider: bot.draftProvider,
+		sceneRuntime:  bot,
+		payloadType:   bot.payloadType,
+		ctx:           ctx,
+	}
+	bot.prepareUpdateCtx(u, msgCtx)
+
+	for _, middleware := range bot.middlewares {
+		if !middleware.Execute(msgCtx, bot.dbContext) {
+			return
+		}
+	}
+
+	sceneHandled, err := bot.tryHandleScene(msgCtx)
+	if err != nil {
+		bot.logger.Errorln(err)
+		return
+	}
+	if sceneHandled {
+		return
+	}
+
+	switch u.Type {
+	case tgapi.UpdateTypeMessage, tgapi.UpdateTypeChannelPost:
+		bot.handleMessage(u, msgCtx)
+	case tgapi.UpdateTypeCallbackQuery:
+		bot.handleCallback(u, msgCtx)
+	default:
+		bot.handleUpdate(u, msgCtx)
+	}
+}
+
+func (bot *Bot[T]) handleMessage(update *tgapi.Update, ctx *MsgContext) {
+	var msg *tgapi.Message
+	if update.Message != nil {
+		msg = update.Message
+	} else if update.ChannelPost != nil {
+		msg = update.ChannelPost
+	} else {
 		return
 	}
 
 	var text string
-	if len(update.Message.Text) > 0 {
-		text = update.Message.Text
+	if len(msg.Text) > 0 {
+		text = msg.Text
+	} else if len(msg.Caption) > 0 {
+		text = msg.Caption
 	} else {
-		text = update.Message.Caption
+		return
 	}
 
-	text = strings.TrimSpace(text)
-	prefix, hasPrefix := b.checkPrefixes(text)
-	if !hasPrefix {
+	prefix, cmd, args := bot.parseCommand(text)
+	if cmd == "" {
 		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):])
+	if strings.Contains(cmd, "@") {
+		botUsername := bot.username
+		if botUsername != "" && strings.HasSuffix(cmd, "@"+botUsername) {
+			cmd = cmd[:len(cmd)-len("@"+botUsername)] // убираем @botname
+		}
+	}
 
-	for _, plugin := range b.plugins {
-		// Check every command
-		for cmd := range plugin.Commands {
-			if !strings.HasPrefix(text, cmd) {
-				continue
+	// Ищем команду по точному совпадению
+	for _, plugin := range bot.plugins {
+		if _, exists := plugin.commands[cmd]; exists {
+			ctx.Text = args
+			ctx.Args = strings.Fields(args) // Убирает лишние пробелы
+
+			if plugin.logger != nil {
+				ctx.Logger = plugin.logger
 			}
-			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):])
-			ctx.Args = strings.Split(ctx.Text, " ")
-
-			if !plugin.executeMiddlewares(ctx, b.dbContext) {
+			if !plugin.executeMiddlewares(ctx, bot.dbContext) {
 				return
 			}
-			go plugin.Execute(cmd, ctx, b.dbContext)
+			plugin.executeCmd(cmd, ctx, bot.dbContext)
 			return
 		}
 	}
 }
 
-func (b *Bot) handleCallback(update *Update, ctx *MsgContext) {
-	data := new(CallbackData)
-	err := json.Unmarshal([]byte(update.CallbackQuery.Data), data)
+func (bot *Bot[T]) handleCallback(update *tgapi.Update, ctx *MsgContext) {
+	data, err := bot.decodePayload(update.CallbackQuery.Data)
 	if err != nil {
-		b.logger.Errorln(err)
+		bot.logger.Errorln(err)
 		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 b.plugins {
-		_, ok := plugin.Payloads[data.Command]
+	for _, plugin := range bot.plugins {
+		_, ok := plugin.payloads[data.Command]
 		if !ok {
 			continue
 		}
 
-		if !plugin.executeMiddlewares(ctx, b.dbContext) {
+		ctx.Logger = plugin.logger
+		if ctx.Logger == nil {
+			ctx.Logger = bot.logger
+		}
+		if !plugin.executeMiddlewares(ctx, bot.dbContext) {
 			return
 		}
-		go plugin.ExecutePayload(data.Command, ctx, b.dbContext)
+		plugin.executePayload(data.Command, ctx, bot.dbContext)
 		return
 	}
 }
 
-func (b *Bot) checkPrefixes(text string) (string, bool) {
-	for _, prefix := range b.prefixes {
+func (bot *Bot[T]) handleUpdate(u *tgapi.Update, ctx *MsgContext) {
+	for _, plugin := range bot.plugins {
+		handler, ok := plugin.handlers[u.Type]
+		if !ok {
+			continue
+		}
+
+		pluginCtx := cloneMsgContext(ctx)
+		if plugin.logger != nil {
+			pluginCtx.Logger = plugin.logger
+		}
+		if !plugin.executeMiddlewares(pluginCtx, bot.dbContext) {
+			continue
+		}
+		if err := handler(pluginCtx, bot.dbContext); err != nil {
+			pluginCtx.error(err)
+		}
+	}
+}
+
+func cloneMsgContext(src *MsgContext) *MsgContext {
+	cloned := *src
+	if src.Args != nil {
+		cloned.Args = append([]string(nil), src.Args...)
+	}
+	return &cloned
+}
+
+func (bot *Bot[T]) prepareUpdateCtx(u *tgapi.Update, ctx *MsgContext) {
+	var from *tgapi.User
+	switch u.Type {
+	case tgapi.UpdateTypeMessage:
+		if u.Message != nil {
+			ctx.Msg = u.Message
+		}
+	case tgapi.UpdateTypeEditedMessage:
+		if u.EditedMessage != nil {
+			ctx.Msg = u.EditedMessage
+		}
+	case tgapi.UpdateTypeChannelPost:
+		if u.ChannelPost != nil {
+			ctx.Msg = u.ChannelPost
+		}
+	case tgapi.UpdateTypeEditedChannelPost:
+		if u.EditedChannelPost != nil {
+			ctx.Msg = u.EditedChannelPost
+		}
+	case tgapi.UpdateTypeBusinessMessage:
+		if u.BusinessMessage != nil {
+			ctx.Msg = u.BusinessMessage
+		}
+	case tgapi.UpdateTypeEditedBusinessMessage:
+		if u.EditedBusinessMessage != nil {
+			ctx.Msg = u.EditedBusinessMessage
+		}
+	case tgapi.UpdateTypeInlineQuery:
+		if u.InlineQuery != nil {
+			from = &u.InlineQuery.From
+		}
+	case tgapi.UpdateTypeChosenInlineResult:
+		if u.ChosenInlineResult != nil {
+			from = &u.ChosenInlineResult.From
+		}
+	case tgapi.UpdateTypeCallbackQuery:
+		if u.CallbackQuery != nil {
+			if u.CallbackQuery.Message != nil {
+				ctx.Msg = u.CallbackQuery.Message
+				ctx.CallbackMsgId = u.CallbackQuery.Message.MessageID
+			}
+			if u.CallbackQuery.InlineMessageID != nil {
+				ctx.InlineMsgId = *u.CallbackQuery.InlineMessageID
+			}
+			ctx.CallbackQueryId = u.CallbackQuery.ID
+			from = &u.CallbackQuery.From
+		}
+	case tgapi.UpdateTypeShippingQuery:
+		if u.ShippingQuery != nil {
+			from = &u.ShippingQuery.From
+		}
+	case tgapi.UpdateTypePreCheckoutQuery:
+		if u.PreCheckoutQuery != nil {
+			from = &u.PreCheckoutQuery.From
+		}
+	case tgapi.UpdateTypePurchasedPaidMedia:
+		if u.PurchasedPaidMedia != nil {
+			from = &u.PurchasedPaidMedia.From
+		}
+	case tgapi.UpdateTypeMyChatMember:
+		if u.MyChatMember != nil {
+			from = &u.MyChatMember.From
+		}
+	case tgapi.UpdateTypeChatMember:
+		if u.ChatMember != nil {
+			from = &u.ChatMember.From
+		}
+	case tgapi.UpdateTypeChatJoinRequest:
+		if u.ChatJoinRequest != nil {
+			from = &u.ChatJoinRequest.From
+		}
+	case tgapi.UpdateTypeBusinessConnection:
+		if u.BusinessConnection != nil {
+			from = &u.BusinessConnection.User
+		}
+	case tgapi.UpdateTypePollAnswer:
+		if u.PollAnswer != nil {
+			from = &u.PollAnswer.User
+		}
+	case tgapi.UpdateTypeMessageReaction:
+		if u.MessageReaction != nil {
+			from = u.MessageReaction.User
+		}
+	case tgapi.UpdateTypeChatBoost:
+		if u.ChatBoost != nil {
+			from = &u.ChatBoost.Boost.Source.User
+		}
+	case tgapi.UpdateTypeRemovedChatBoost:
+		if u.RemovedChatBoost != nil {
+			from = &u.RemovedChatBoost.Source.User
+		}
+	}
+	if ctx.Msg != nil && from == nil {
+		from = ctx.Msg.From
+	}
+	if from != nil {
+		ctx.From = from
+		ctx.FromID = from.ID
+	}
+}
+
+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 "", "", ""
+}
+
+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) {
+	var data CallbackData
+	err := json.Unmarshal([]byte(s), &data)
+	return data, err
+}
+func encodeBase64Payload(d CallbackData) (string, error) {
+	data, err := encodeJsonPayload(d)
+	if err != nil {
+		return "", err
+	}
+	dst := make([]byte, base64.RawURLEncoding.EncodedLen(len([]byte(data))))
+	base64.RawURLEncoding.Encode(dst, []byte(data))
+	return string(dst), nil
+}
+
+//	func encodePayload(payloadType BotPayloadType, d CallbackData) (string, error) {
+//		switch payloadType {
+//		case BotPayloadBase64:
+//			return encodeBase64Payload(d)
+//		case BotPayloadJson:
+//			return encodeJsonPayload(d)
+//		}
+//		return "", ErrInvalidPayloadType
+//	}
+func decodeBase64Payload(s string) (CallbackData, error) {
+	b, err := base64.RawURLEncoding.DecodeString(s)
+	if err != nil {
+		return CallbackData{}, err
+	}
+	return decodeJsonPayload(string(b))
+}
+func decodePayload(payloadType BotPayloadType, s string, strict bool) (CallbackData, BotPayloadType, error) {
+	switch payloadType {
+	case BotPayloadBase64:
+		data, err := decodeBase64Payload(s)
+		if err == nil {
+			return data, BotPayloadBase64, nil
+		}
+		if strict {
+			return CallbackData{}, "", fmt.Errorf("%w: expected %s", ErrPayloadTypeMismatch, BotPayloadBase64)
+		}
+		data, err = decodeJsonPayload(s)
+		if err != nil {
+			return CallbackData{}, "", err
+		}
+		return data, BotPayloadJson, nil
+	case BotPayloadJson:
+		data, err := decodeJsonPayload(s)
+		if err == nil {
+			return data, BotPayloadJson, nil
+		}
+		if strict {
+			return CallbackData{}, "", fmt.Errorf("%w: expected %s", ErrPayloadTypeMismatch, BotPayloadJson)
+		}
+		data, err = decodeBase64Payload(s)
+		if err != nil {
+			return CallbackData{}, "", err
+		}
+		return data, BotPayloadBase64, nil
+	}
+	return CallbackData{}, "", ErrInvalidPayloadType
+}
+
+//	func (bot *Bot[T]) encodePayload(d CallbackData) (string, error) {
+//		return encodePayload(bot.payloadType, d)
+//	}
+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
+}

handler_test.go

@@ -0,0 +1,325 @@
+package laniakea
+
+import (
+	"context"
+	"testing"
+
+	"git.scuroneko.dev/scuroneko/laniakea/tgapi"
+	"git.scuroneko.dev/scuroneko/slog"
+)
+
+func TestCheckPrefixesSkipsEmptyPrefixes(t *testing.T) {
+	bot := &Bot[NoDB]{prefixes: []string{"", "/"}}
+
+	if prefix, ok := bot.checkPrefixes("hello"); ok {
+		t.Fatalf("unexpected prefix match for plain text: %q", prefix)
+	}
+	if prefix, ok := bot.checkPrefixes("/start"); !ok || prefix != "/" {
+		t.Fatalf("unexpected prefix result: prefix=%q ok=%v", prefix, ok)
+	}
+}
+
+func TestBotMiddlewareReceivesLogger(t *testing.T) {
+	logger := slog.CreateLogger()
+	called := false
+
+	bot := &Bot[NoDB]{
+		logger: logger,
+		middlewares: []Middleware[NoDB]{
+			NewMiddleware("logger-check", func(ctx *MsgContext, db NoDB) bool {
+				called = true
+				if ctx.Logger != logger {
+					t.Fatalf("expected bot logger in middleware context, got %#v", ctx.Logger)
+				}
+				return true
+			}),
+		},
+	}
+
+	bot.handle(context.Background(), &tgapi.Update{
+		UpdateID: 1,
+		Type:     tgapi.UpdateTypePoll,
+		Poll: &tgapi.Poll{
+			ID:       "poll",
+			Question: "question",
+		},
+	})
+
+	if !called {
+		t.Fatal("expected bot middleware to be called")
+	}
+}
+
+func TestAddUpdateHandlerRejectsReservedUpdateTypes(t *testing.T) {
+	plugin := NewPlugin[NoDB]("test")
+	handler := func(ctx *MsgContext, db NoDB) error { return nil }
+
+	for _, updateType := range []tgapi.UpdateType{
+		tgapi.UpdateTypeMessage,
+		tgapi.UpdateTypeChannelPost,
+		tgapi.UpdateTypeCallbackQuery,
+	} {
+		func() {
+			defer func() {
+				if r := recover(); r != nil {
+					t.Fatalf("AddUpdateHandler(%q) panicked: %v", updateType, r)
+				}
+			}()
+			plugin.AddUpdateHandler(updateType, handler)
+		}()
+
+		if _, ok := plugin.handlers[updateType]; ok {
+			t.Fatalf("reserved update type %q must not be registered", updateType)
+		}
+	}
+}
+
+func TestHandleUpdateHandlersPopulateFromContext(t *testing.T) {
+	tests := []struct {
+		name   string
+		update *tgapi.Update
+		wantID int64
+	}{
+		{
+			name: "inline query",
+			update: &tgapi.Update{
+				UpdateID: 1,
+				Type:     tgapi.UpdateTypeInlineQuery,
+				InlineQuery: &tgapi.InlineQuery{
+					ID:    "iq",
+					From:  tgapi.User{ID: 41},
+					Query: "ping",
+				},
+			},
+			wantID: 41,
+		},
+		{
+			name: "chosen inline result",
+			update: &tgapi.Update{
+				UpdateID: 2,
+				Type:     tgapi.UpdateTypeChosenInlineResult,
+				ChosenInlineResult: &tgapi.ChosenInlineResult{
+					ResultID: "res",
+					From:     tgapi.User{ID: 77},
+					Query:    "pong",
+				},
+			},
+			wantID: 77,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			called := false
+			plugin := NewPlugin[NoDB]("test").AddUpdateHandler(tt.update.Type, func(ctx *MsgContext, db NoDB) error {
+				called = true
+				if ctx.Update.UpdateID != tt.update.UpdateID {
+					t.Fatalf("unexpected update in context: got %d want %d", ctx.Update.UpdateID, tt.update.UpdateID)
+				}
+				if ctx.From == nil {
+					t.Fatal("expected ctx.From to be populated")
+				}
+				if ctx.FromID != tt.wantID {
+					t.Fatalf("unexpected FromID: got %d want %d", ctx.FromID, tt.wantID)
+				}
+				if ctx.From.ID != tt.wantID {
+					t.Fatalf("unexpected ctx.From.ID: got %d want %d", ctx.From.ID, tt.wantID)
+				}
+				if ctx.Msg != nil {
+					t.Fatalf("did not expect message context for %s", tt.name)
+				}
+				return nil
+			})
+
+			bot := &Bot[NoDB]{
+				logger:  slog.CreateLogger(),
+				plugins: []Plugin[NoDB]{clonePlugin(plugin)},
+			}
+
+			bot.handle(context.Background(), tt.update)
+
+			if !called {
+				t.Fatalf("expected update handler for %s to be called", tt.name)
+			}
+		})
+	}
+}
+
+func TestHandleUpdateHandlersReceiveIsolatedContexts(t *testing.T) {
+	firstCalled := false
+	secondCalled := false
+
+	first := NewPlugin[NoDB]("first").AddUpdateHandler(tgapi.UpdateTypeInlineQuery, func(ctx *MsgContext, db NoDB) error {
+		firstCalled = true
+		if ctx.FromID != 41 {
+			t.Fatalf("unexpected FromID in first handler: got %d want 41", ctx.FromID)
+		}
+		ctx.From = nil
+		ctx.FromID = 999
+		ctx.Text = "mutated"
+		ctx.Args = []string{"mutated"}
+		return nil
+	})
+	second := NewPlugin[NoDB]("second").AddUpdateHandler(tgapi.UpdateTypeInlineQuery, func(ctx *MsgContext, db NoDB) error {
+		secondCalled = true
+		if ctx.From == nil {
+			t.Fatal("expected ctx.From to remain populated for second handler")
+		}
+		if ctx.FromID != 41 {
+			t.Fatalf("unexpected FromID in second handler: got %d want 41", ctx.FromID)
+		}
+		if ctx.Text != "" {
+			t.Fatalf("unexpected leaked Text in second handler: %q", ctx.Text)
+		}
+		if len(ctx.Args) != 0 {
+			t.Fatalf("unexpected leaked Args in second handler: %v", ctx.Args)
+		}
+		return nil
+	})
+
+	bot := &Bot[NoDB]{
+		logger: slog.CreateLogger(),
+		plugins: []Plugin[NoDB]{
+			clonePlugin(first),
+			clonePlugin(second),
+		},
+	}
+
+	bot.handle(context.Background(), &tgapi.Update{
+		UpdateID: 3,
+		Type:     tgapi.UpdateTypeInlineQuery,
+		InlineQuery: &tgapi.InlineQuery{
+			ID:    "iq",
+			From:  tgapi.User{ID: 41},
+			Query: "ping",
+		},
+	})
+
+	if !firstCalled || !secondCalled {
+		t.Fatalf("expected both handlers to be called, got first=%v second=%v", firstCalled, secondCalled)
+	}
+}
+
+func TestHandleChannelPostCommandWithSenderChat(t *testing.T) {
+	called := false
+	plugin := NewPlugin[NoDB]("test")
+	plugin.NewCommand(func(ctx *MsgContext, db NoDB) error {
+		called = true
+		if ctx.Msg == nil {
+			t.Fatal("expected message context")
+		}
+		if ctx.Msg.Chat == nil || ctx.Msg.Chat.ID != -1001 {
+			t.Fatalf("unexpected chat context: %#v", ctx.Msg.Chat)
+		}
+		if ctx.From != nil {
+			t.Fatalf("expected ctx.From to stay nil for sender_chat updates, got %#v", ctx.From)
+		}
+		if ctx.FromID != 0 {
+			t.Fatalf("expected zero FromID for sender_chat updates, got %d", ctx.FromID)
+		}
+		return nil
+	}, "ping")
+
+	bot := &Bot[NoDB]{
+		logger:   slog.CreateLogger(),
+		prefixes: []string{"/"},
+		plugins:  []Plugin[NoDB]{clonePlugin(plugin)},
+	}
+
+	bot.handle(context.Background(), &tgapi.Update{
+		UpdateID: 10,
+		Type:     tgapi.UpdateTypeChannelPost,
+		ChannelPost: &tgapi.Message{
+			MessageID:  55,
+			Text:       "/ping",
+			SenderChat: &tgapi.Chat{ID: -1001, Type: string(tgapi.ChatTypeChannel)},
+			Chat:       &tgapi.Chat{ID: -1001, Type: string(tgapi.ChatTypeChannel)},
+		},
+	})
+
+	if !called {
+		t.Fatal("expected channel post command handler to be called")
+	}
+}
+
+func TestCommandHandlerBindArgsEndToEnd(t *testing.T) {
+	type banInput struct {
+		UserID int
+		Reason string
+	}
+
+	var got banInput
+	plugin := NewPlugin[NoDB]("test")
+	plugin.NewCommand(func(ctx *MsgContext, db NoDB) error {
+		return ctx.BindArgs(&got)
+	}, "ban",
+		NewCommandArg("user_id").SetValueType(CommandValueIntType).SetRequired(),
+		NewCommandArg("reason").SetRequired(),
+	)
+
+	bot := &Bot[NoDB]{
+		logger:   slog.CreateLogger(),
+		prefixes: []string{"/"},
+		plugins:  []Plugin[NoDB]{clonePlugin(plugin)},
+	}
+
+	bot.handle(context.Background(), &tgapi.Update{
+		UpdateID: 11,
+		Type:     tgapi.UpdateTypeMessage,
+		Message: &tgapi.Message{
+			MessageID: 1,
+			Text:      "/ban 42 too loud",
+			Chat:      &tgapi.Chat{ID: 99, Type: string(tgapi.ChatTypePrivate)},
+		},
+	})
+
+	want := banInput{UserID: 42, Reason: "too loud"}
+	if got != want {
+		t.Fatalf("unexpected bound input: got %#v want %#v", got, want)
+	}
+}
+
+func TestPayloadHandlerBindArgsEndToEnd(t *testing.T) {
+	type payloadInput struct {
+		ID   int
+		Note string
+	}
+
+	var got payloadInput
+	plugin := NewPlugin[NoDB]("test")
+	plugin.NewPayload(func(ctx *MsgContext, db NoDB) error {
+		return ctx.BindArgs(&got)
+	}, "approve",
+		NewCommandArg("id").SetValueType(CommandValueIntType).SetRequired(),
+		NewCommandArg("note").SetRequired(),
+	)
+
+	bot := &Bot[NoDB]{
+		logger:      slog.CreateLogger(),
+		payloadType: BotPayloadJson,
+		plugins:     []Plugin[NoDB]{clonePlugin(plugin)},
+	}
+
+	data, err := encodeJsonPayload(CallbackData{
+		Command: "approve",
+		Args:    []string{"7", "looks", "good"},
+	})
+	if err != nil {
+		t.Fatalf("encodeJsonPayload returned error: %v", err)
+	}
+
+	bot.handle(context.Background(), &tgapi.Update{
+		UpdateID: 12,
+		Type:     tgapi.UpdateTypeCallbackQuery,
+		CallbackQuery: &tgapi.CallbackQuery{
+			ID:   "cb-1",
+			Data: data,
+			From: tgapi.User{ID: 1},
+		},
+	})
+
+	want := payloadInput{ID: 7, Note: "looks good"}
+	if got != want {
+		t.Fatalf("unexpected bound payload input: got %#v want %#v", got, want)
+	}
+}

keyboard.go

@@ -1,74 +1,291 @@
 package laniakea
 
 import (
-	"encoding/json"
 	"fmt"
+
+	"git.scuroneko.dev/scuroneko/extypes"
+	"git.scuroneko.dev/scuroneko/laniakea/tgapi"
 )
 
+const (
+	// 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"
+)
+
+// InlineKbButtonBuilder is a fluent builder for creating a single inline keyboard button.
+//
+// Use NewInlineKbButton() to start, then chain methods to configure:
+//   - SetIconCustomEmojiId() — adds a custom emoji icon
+//   - SetStyle() — sets visual style (danger/success/primary)
+//   - SetUrl() — makes button open a URL
+//   - SetCallbackDataJson() — attaches structured command + args for bot handling
+//
+// Call build() to produce the final tgapi.InlineKeyboardButton.
+// Builder methods are immutable — each returns a copy.
+type InlineKbButtonBuilder struct {
+	text              string
+	iconCustomEmojiID string
+	style             tgapi.KeyboardButtonStyle
+	url               string
+	callbackData      string
+}
+
+// NewInlineKbButton creates a new button builder with the given display text.
+// The button will have no URL, no style, and no callback data by default.
+func NewInlineKbButton(text string) InlineKbButtonBuilder {
+	return InlineKbButtonBuilder{text: text}
+}
+
+// SetIconCustomEmojiId sets a custom emoji ID to display as the button's icon.
+// This is a Telegram Bot API feature for custom emoji icons.
+func (b InlineKbButtonBuilder) SetIconCustomEmojiId(id string) InlineKbButtonBuilder {
+	b.iconCustomEmojiID = id
+	return b
+}
+
+// SetStyle sets the visual style of the button.
+// Valid values: ButtonStyleDanger, ButtonStyleSuccess, ButtonStylePrimary.
+// If not set, the button uses the default style.
+func (b InlineKbButtonBuilder) SetStyle(style tgapi.KeyboardButtonStyle) InlineKbButtonBuilder {
+	b.style = style
+	return b
+}
+
+// SetUrl sets a URL that will be opened when the button is pressed.
+// If both URL and CallbackData are set, Telegram will prioritize URL.
+func (b InlineKbButtonBuilder) SetUrl(url string) InlineKbButtonBuilder {
+	b.url = url
+	return b
+}
+
+// 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 InlineKbButtonBuilder) SetCallbackDataJson(cmd string, args ...any) InlineKbButtonBuilder {
+	b.callbackData = NewCallbackData(cmd, args...).ToJson()
+	return b
+}
+
+// SetCallbackDataBase64 sets a structured callback payload encoded as Base64.
+// This can be useful when the JSON payload exceeds Telegram's callback data length limit.
+// Args are converted to strings using fmt.Sprint.
+func (b InlineKbButtonBuilder) SetCallbackDataBase64(cmd string, args ...any) InlineKbButtonBuilder {
+	b.callbackData = NewCallbackData(cmd, args...).ToBase64()
+	return b
+}
+
+// Internal helper that converts the builder state into a Telegram button.
+func (b InlineKbButtonBuilder) build() tgapi.InlineKeyboardButton {
+	return tgapi.InlineKeyboardButton{
+		Text:              b.text,
+		URL:               b.url,
+		Style:             b.style,
+		IconCustomEmojiID: b.iconCustomEmojiID,
+		CallbackData:      b.callbackData,
+	}
+}
+
+// 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 []InlineKeyboardButton
-	Lines       [][]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)
+}
+
+// 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([]InlineKeyboardButton, 0),
-		Lines:       make([][]InlineKeyboardButton, 0),
+		CurrentLine: make(extypes.Slice[tgapi.InlineKeyboardButton], 0),
+		Lines:       make([][]tgapi.InlineKeyboardButton, 0),
 		maxRow:      maxRow,
+		payloadType: payloadType,
 	}
 }
 
-func (in *InlineKeyboard) append(button InlineKeyboardButton) *InlineKeyboard {
-	if len(in.CurrentLine) == in.maxRow {
-		in.AddLine()
-	}
-	in.CurrentLine = append(in.CurrentLine, button)
+// 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
 }
-func (in *InlineKeyboard) AddUrlButton(text, url string) *InlineKeyboard {
-	return in.append(InlineKeyboardButton{Text: text, URL: url})
-}
-func (in *InlineKeyboard) AddCallbackButton(text string, cmd string, args ...any) *InlineKeyboard {
-	return in.append(InlineKeyboardButton{Text: text, CallbackData: NewCallbackData(cmd, args...).ToJson()})
+
+// GetPayloadType returns the keyboard-local callback payload encoding type.
+func (in *InlineKeyboard) GetPayloadType() BotPayloadType { return in.payloadType }
+
+func (in *InlineKeyboard) SetMaxRow(maxRow int) *InlineKeyboard {
+	in.maxRow = maxRow
+	return in
 }
 
+// Internal helper that appends a button and auto-flushes a full row.
+func (in *InlineKeyboard) append(button tgapi.InlineKeyboardButton) *InlineKeyboard {
+	if in.CurrentLine.Len() == in.maxRow {
+		in.AddLine()
+	}
+	in.CurrentLine = in.CurrentLine.Push(button)
+	return in
+}
+
+// AddUrlButton adds a button that opens a URL when pressed.
+// No callback data is attached.
+func (in *InlineKeyboard) AddUrlButton(text, url string) *InlineKeyboard {
+	return in.append(tgapi.InlineKeyboardButton{Text: text, URL: url})
+}
+
+// AddUrlButtonStyle adds a button with a visual style that opens a URL.
+// Style must be one of: ButtonStyleDanger, ButtonStyleSuccess, ButtonStylePrimary.
+func (in *InlineKeyboard) AddUrlButtonStyle(text string, style tgapi.KeyboardButtonStyle, url string) *InlineKeyboard {
+	return in.append(tgapi.InlineKeyboardButton{Text: text, Style: style, URL: url})
+}
+
+// AddCallbackButton adds a button that sends a structured callback payload to the bot.
+// The command and args are serialized according to the current payloadType.
+func (in *InlineKeyboard) AddCallbackButton(text string, cmd string, args ...any) *InlineKeyboard {
+	return in.append(tgapi.InlineKeyboardButton{
+		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...).Encode(in.payloadType),
+	})
+}
+
+// AddButton adds a button pre-configured via InlineKbButtonBuilder.
+// This is the most flexible way to create buttons with custom emoji, style, URL, and callback.
+func (in *InlineKeyboard) AddButton(b InlineKbButtonBuilder) *InlineKeyboard {
+	return in.append(b.build())
+}
+
+// AddLine manually ends the current row and starts a new one.
+// If the current row is empty, nothing happens.
 func (in *InlineKeyboard) AddLine() *InlineKeyboard {
-	if len(in.CurrentLine) == 0 {
+	if in.CurrentLine.Len() == 0 {
 		return in
 	}
 	in.Lines = append(in.Lines, in.CurrentLine)
-	in.CurrentLine = make([]InlineKeyboardButton, 0)
+	in.CurrentLine = make(extypes.Slice[tgapi.InlineKeyboardButton], 0)
 	return in
 }
-func (in *InlineKeyboard) Get() *InlineKeyboardMarkup {
-	if len(in.CurrentLine) > 0 {
-		in.Lines = append(in.Lines, in.CurrentLine)
-	}
-	return &InlineKeyboardMarkup{
-		InlineKeyboard: in.Lines,
+
+// 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.AddLine()
 	}
+	return &tgapi.ReplyMarkup{InlineKeyboard: in.Lines}
 }
 
+// CallbackData represents the structured payload sent when an inline button
+// with callback data is pressed.
+//
+// This structure is serialized to JSON and sent to the bot as a string.
+// The bot should parse this back to determine the command and arguments.
+//
+// Example:
+//
+//	{"cmd":"delete_user","args":["123","confirm"]}
 type CallbackData struct {
-	Command string   `json:"cmd"`
-	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{
+	return CallbackData{
 		Command: command,
 		Args:    stringArgs,
 	}
 }
-func (d *CallbackData) ToJson() string {
-	data, err := json.Marshal(d)
+
+// ToJson serializes the CallbackData to a JSON string.
+//
+// If serialization fails (e.g., due to unmarshalable fields), returns a fallback
+// JSON object: {"cmd":""} to prevent breaking Telegram's API.
+//
+// This fallback ensures the bot receives a valid JSON payload even if internal
+// errors occur — avoiding "invalid callback_data" errors from Telegram.
+func (d CallbackData) ToJson() string {
+	data, err := encodeJsonPayload(d)
 	if err != nil {
+		// Fallback: return minimal valid JSON to avoid Telegram API rejection
 		return `{"cmd":""}`
 	}
-	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 {
+	s, err := encodeBase64Payload(d)
+	if err != nil {
+		return ``
+	}
+	return s
+}
+
+// Encode serializes the CallbackData according to the specified payload type.
+// Supported types: BotPayloadJson and BotPayloadBase64.
+// 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()
+	}
+	return ""
 }

keyboard_test.go

@@ -0,0 +1,97 @@
+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(
+			NewInlineKbButton("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 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 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

@@ -0,0 +1,71 @@
+package laniakea
+
+import "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{
+		entries:      make(map[string]DictEntry),
+		fallbackLang: fallbackLanguage,
+	}
+}
+
+// AddDictEntry stores translations for key.
+func (l *L10n) AddDictEntry(key string, value DictEntry) *L10n {
+	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 {
+	l.mu.RLock()
+	defer l.mu.RUnlock()
+
+	entries, exists := l.entries[key]
+	if !exists {
+		return key
+	}
+
+	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))
+	for lang, text := range src {
+		cloned[lang] = text
+	}
+	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,362 +1,69 @@
 package laniakea
 
 import (
+	"context"
 	"encoding/json"
-	"fmt"
+
+	"git.scuroneko.dev/scuroneko/laniakea/tgapi"
 )
 
-type EmptyParams struct{}
-
-var NoParams = EmptyParams{}
-
-type UpdateParams struct {
-	Offset         int      `json:"offset"`
-	Timeout        int      `json:"timeout"`
-	AllowedUpdates []string `json:"allowed_updates"`
-}
-
-func (b *Bot) Updates() ([]*Update, error) {
-	params := UpdateParams{
-		Offset:         b.updateOffset,
-		Timeout:        30,
-		AllowedUpdates: b.updateTypes,
+// 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 30-second timeout
+//  3. Filters updates by types specified in bot.GetUpdateTypes()
+//  4. Logs raw update JSON if RequestLogger is configured
+//  5. Automatically updates the offset to the last received update ID + 1
+//  6. Returns all received updates (empty slice if none)
+//
+// Note: This is a blocking call that waits up to 30 seconds for new updates,
+// 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()
+	params := tgapi.UpdateParams{
+		Offset:         Ptr(offset),
+		Timeout:        Ptr(30),
+		AllowedUpdates: bot.GetUpdateTypes(),
 	}
 
-	req := NewRequest[[]*Update]("getUpdates", params)
-	res, err := req.Do(b.api)
+	updates, err := bot.api.GetUpdatesWithContext(ctx, params)
 	if err != nil {
-		return []*Update{}, err
+		return nil, err
 	}
-	updates := *res
 
-	for _, u := range updates {
-		b.updateOffset = u.UpdateID + 1
-		err = b.updateQueue.Enqueue(u)
-		if err != nil {
-			return updates, err
-		}
-
-		if b.debug && b.requestLogger != nil {
+	if bot.RequestLogger != nil {
+		for _, u := range updates {
 			j, err := json.Marshal(u)
 			if err != nil {
-				b.logger.Error(err)
+				bot.GetLogger().Error(err)
 			}
-			b.requestLogger.Debugln(fmt.Sprintf("UPDATE %s", j))
+			bot.RequestLogger.Debugf("UPDATE %s\n", j)
 		}
 	}
+	if len(updates) > 0 {
+		bot.SetUpdateOffset(updates[len(updates)-1].UpdateID + 1)
+	}
 	return updates, err
 }
-
-func (api *Api) GetMe() (*User, error) {
-	req := NewRequest[User, EmptyParams]("getMe", NoParams)
-	return req.Do(api)
-}
-func (api *Api) LogOut() (bool, error) {
-	req := NewRequest[bool, EmptyParams]("logOut", NoParams)
-	res, err := req.Do(api)
-	if err != nil {
-		return false, err
-	}
-	return *res, nil
-}
-func (api *Api) Close() (bool, error) {
-	req := NewRequest[bool, EmptyParams]("close", NoParams)
-	res, err := req.Do(api)
-	if err != nil {
-		return false, err
-	}
-	return *res, nil
-}
-
-type SendMessageP struct {
-	BusinessConnectionID string `json:"business_connection_id,omitempty"`
-	ChatID               int    `json:"chat_id"`
-	MessageThreadID      int    `json:"message_thread_id,omitempty"`
-	DirectMessageTopicID int    `json:"direct_message_topic_id,omitempty"`
-
-	Text                 string              `json:"text"`
-	ParseMode            ParseMode           `json:"parse_mode,omitempty"`
-	Entities             []*MessageEntity    `json:"entities,omitempty"`
-	LinkPreviewOptions   *LinkPreviewOptions `json:"link_preview_options,omitempty"`
-	DisableNotifications bool                `json:"disable_notifications,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"`
-}
-
-func (api *Api) SendMessage(params *SendMessageP) (*Message, error) {
-	req := NewRequest[Message, SendMessageP]("sendMessage", *params)
-	return req.Do(api)
-}
-
-type ForwardMessageP struct {
-	ChatID               int `json:"chat_id"`
-	MessageThreadID      int `json:"message_thread_id,omitempty"`
-	DirectMessageTopicID int `json:"direct_message_topic_id,omitempty"`
-
-	MessageID           int  `json:"message_id,omitempty"`
-	FromChatID          int  `json:"from_chat_id,omitempty"`
-	VideoStartTimestamp int  `json:"video_start_timestamp,omitempty"`
-	DisableNotification bool `json:"disable_notification,omitempty"`
-	ProtectContent      bool `json:"protect_content,omitempty"`
-
-	MessageEffectID         string                   `json:"message_effect_id,omitempty"`
-	SuggestedPostParameters *SuggestedPostParameters `json:"suggested_post_parameters,omitempty"`
-}
-
-func (api *Api) ForwardMessage(params ForwardMessageP) (*Message, error) {
-	req := NewRequest[Message]("forwardMessage", params)
-	return req.Do(api)
-}
-
-type ForwardMessagesP struct {
-	ChatID               int `json:"chat_id"`
-	MessageThreadID      int `json:"message_thread_id,omitempty"`
-	DirectMessageTopicID int `json:"direct_message_topic_id,omitempty"`
-
-	FromChatID          int   `json:"from_chat_id,omitempty"`
-	MessageIDs          []int `json:"message_ids,omitempty"`
-	DisableNotification bool  `json:"disable_notification,omitempty"`
-	ProtectContent      bool  `json:"protect_content,omitempty"`
-}
-
-func (api *Api) ForwardMessages(params ForwardMessagesP) ([]int, error) {
-	req := NewRequest[[]int]("forwardMessages", params)
-	res, err := req.Do(api)
-	if err != nil {
-		return []int{}, err
-	}
-	return *res, nil
-}
-
-type CopyMessageP struct {
-	ChatID               int `json:"chat_id"`
-	MessageThreadID      int `json:"message_thread_id,omitempty"`
-	DirectMessageTopicID int `json:"direct_message_topic_id,omitempty"`
-
-	FromChatID          int       `json:"from_chat_id"`
-	MessageID           int       `json:"message_id"`
-	VideoStartTimestamp int       `json:"video_start_timestamp,omitempty"`
-	Caption             string    `json:"caption,omitempty"`
-	ParseMode           ParseMode `json:"parse_mode,omitempty"`
-
-	CaptionEntities       []*MessageEntity `json:"caption_entities,omitempty"`
-	ShowCaptionAboveMedia bool             `json:"show_caption_above_media,omitempty"`
-	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"`
-}
-
-func (api *Api) CopyMessage(params CopyMessageP) (int, error) {
-	req := NewRequest[int]("copyMessage", params)
-	res, err := req.Do(api)
-	if err != nil {
-		return 0, err
-	}
-	return *res, nil
-}
-
-type CopyMessagesP struct {
-	ChatID               int `json:"chat_id"`
-	MessageThreadID      int `json:"message_thread_id,omitempty"`
-	DirectMessageTopicID int `json:"direct_message_topic_id,omitempty"`
-
-	FromChatID          int   `json:"from_chat_id,omitempty"`
-	MessageIDs          []int `json:"message_ids,omitempty"`
-	DisableNotification bool  `json:"disable_notification,omitempty"`
-	ProtectContent      bool  `json:"protect_content,omitempty"`
-	RemoveCaption       bool  `json:"remove_caption,omitempty"`
-}
-
-func (api *Api) CopyMessages(params CopyMessagesP) ([]int, error) {
-	req := NewRequest[[]int]("copyMessages", params)
-	res, err := req.Do(api)
-	if err != nil {
-		return []int{}, err
-	}
-	return *res, nil
-}
-
-type SendPhotoBaseP struct {
-	BusinessConnectionID  string                `json:"business_connection_id,omitempty"`
-	ChatID                int                   `json:"chat_id"`
-	MessageThreadID       int                   `json:"message_thread_id,omitempty"`
-	ParseMode             ParseMode             `json:"parse_mode,omitempty"`
-	Caption               string                `json:"caption,omitempty"`
-	CaptionEntities       []*MessageEntity      `json:"caption_entities,omitempty"`
-	ShowCaptionAboveMedia bool                  `json:"show_caption_above_media,omitempty"`
-	HasSpoiler            bool                  `json:"has_spoiler,omitempty"`
-	DisableNotifications  bool                  `json:"disable_notifications,omitempty"`
-	ProtectContent        bool                  `json:"protect_content,omitempty"`
-	AllowPaidBroadcast    bool                  `json:"allow_paid_broadcast,omitempty"`
-	MessageEffectID       string                `json:"message_effect_id,omitempty"`
-	ReplyMarkup           *InlineKeyboardMarkup `json:"reply_markup,omitempty"`
-}
-type SendPhotoP struct {
-	BusinessConnectionID  string `json:"business_connection_id,omitempty"`
-	ChatID                int    `json:"chat_id"`
-	MessageThreadID       int    `json:"message_thread_id,omitempty"`
-	DirectMessagesTopicID int    `json:"direct_messages_topic_id,omitempty"`
-
-	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"`
-	DisableNotifications  bool   `json:"disable_notifications,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"`
-}
-
-func (api *Api) SendPhoto(params *SendPhotoP) (*Message, error) {
-	req := NewRequest[Message]("sendPhoto", params)
-	return req.Do(api)
-}
-
-type EditMessageTextP struct {
-	BusinessConnectionID string                `json:"business_connection_id,omitempty"`
-	ChatID               int                   `json:"chat_id,omitempty"`
-	MessageID            int                   `json:"message_id,omitempty"`
-	InlineMessageID      string                `json:"inline_message_id,omitempty"`
-	Text                 string                `json:"text"`
-	ParseMode            ParseMode             `json:"parse_mode,omitempty"`
-	ReplyMarkup          *InlineKeyboardMarkup `json:"reply_markup,omitempty"`
-}
-
-func (api *Api) EditMessageText(params *EditMessageTextP) (*Message, error) {
-	req := NewRequest[Message]("editMessageText", params)
-	return req.Do(api)
-}
-
-type EditMessageCaptionP struct {
-	BusinessConnectionID string                `json:"business_connection_id,omitempty"`
-	ChatID               int                   `json:"chat_id,omitempty"`
-	MessageID            int                   `json:"message_id,omitempty"`
-	InlineMessageID      string                `json:"inline_message_id,omitempty"`
-	Caption              string                `json:"caption"`
-	ParseMode            ParseMode             `json:"parse_mode,omitempty"`
-	ReplyMarkup          *InlineKeyboardMarkup `json:"reply_markup,omitempty"`
-}
-
-func (api *Api) EditMessageCaption(params *EditMessageCaptionP) (*Message, error) {
-	req := NewRequest[Message]("editMessageCaption", params)
-	return req.Do(api)
-}
-
-type DeleteMessageP struct {
-	ChatID    int `json:"chat_id"`
-	MessageID int `json:"message_id"`
-}
-
-func (api *Api) DeleteMessage(params *DeleteMessageP) (bool, error) {
-	req := NewRequest[bool]("deleteMessage", params)
-	ok, err := req.Do(api)
-	if err != nil {
-		return false, err
-	}
-	return *ok, err
-}
-
-type AnswerCallbackQueryP struct {
-	CallbackQueryID string `json:"callback_query_id"`
-	Text            string `json:"text,omitempty"`
-	ShowAlert       bool   `json:"show_alert,omitempty"`
-	URL             string `json:"url,omitempty"`
-	CacheTime       int    `json:"cache_time,omitempty"`
-}
-
-func (api *Api) AnswerCallbackQuery(params *AnswerCallbackQueryP) (bool, error) {
-	req := NewRequest[bool]("answerCallbackQuery", params)
-	ok, err := req.Do(api)
-	if err != nil {
-		return false, err
-	}
-	return *ok, err
-}
-
-type GetFileP struct {
-	FileId string `json:"file_id"`
-}
-
-func (api *Api) GetFile(params *GetFileP) (*File, error) {
-	req := NewRequest[File]("getFile", params)
-	return req.Do(api)
-}
-
-type SendChatActionP struct {
-	BusinessConnectionID string      `json:"business_connection_id,omitempty"`
-	ChatID               int         `json:"chat_id"`
-	MessageThreadID      int         `json:"message_thread_id,omitempty"`
-	Action               ChatActions `json:"action"`
-}
-
-func (api *Api) SendChatAction(params SendChatActionP) (bool, error) {
-	req := NewRequest[bool]("sendChatAction", params)
-	res, err := req.Do(api)
-	if err != nil {
-		return false, err
-	}
-	return *res, err
-}
-
-type SetMessageReactionP struct {
-	ChatId    int  `json:"chat_id"`
-	MessageId int  `json:"message_id"`
-	IsBig     bool `json:"is_big,omitempty"`
-}
-type SetMessageReactionEmojiP struct {
-	SetMessageReactionP
-	Reaction []ReactionTypeEmoji `json:"reaction"`
-}
-
-func (api *Api) SetMessageReactionEmoji(params SetMessageReactionEmojiP) (bool, error) {
-	req := NewRequest[bool]("setMessageReaction", params)
-	res, err := req.Do(api)
-	if err != nil {
-		return false, err
-	}
-	return *res, err
-}
-
-type SetMessageReactionCustomEmojiP struct {
-	SetMessageReactionP
-	Reaction []ReactionTypeCustomEmoji `json:"reaction"`
-}
-
-func (api *Api) SetMessageReactionCustom(params SetMessageReactionCustomEmojiP) (bool, error) {
-	req := NewRequest[bool]("setMessageReaction", params)
-	res, err := req.Do(api)
-	if err != nil {
-		return false, err
-	}
-	return *res, err
-}
-
-type SetMessageReactionPaidP struct {
-	SetMessageReactionP
-}
-
-func (api *Api) SetMessageReactionPaid(params SetMessageReactionPaidP) (bool, error) {
-	req := NewRequest[bool]("setMessageReaction", params)
-	res, err := req.Do(api)
-	if err != nil {
-		return false, err
-	}
-	return *res, err
-}

msg_context.go

@@ -1,210 +1,729 @@
 package laniakea
 
-import "fmt"
+import (
+	"context"
+	"errors"
+	"fmt"
+	"reflect"
+	"strconv"
+	"strings"
+	"time"
 
+	"git.scuroneko.dev/scuroneko/laniakea/tgapi"
+	"git.scuroneko.dev/scuroneko/slog"
+)
+
+// MsgContext holds the context for handling a Telegram message or callback query.
+// It provides methods to respond, edit, delete, and translate messages, as well as
+// manage inline keyboards and message drafts.
 type MsgContext struct {
-	Bot *Bot
-	Api *Api
+	Api    *tgapi.API
+	Update tgapi.Update
 
-	Msg             *Message
-	Update          *Update
-	From            *User
+	Msg  *tgapi.Message
+	From *tgapi.User
+
+	// Logger is the logger assigned by the matched plugin for the current handler call.
+	// It may fall back to the bot logger when the plugin has no dedicated logger.
+	Logger *slog.Logger
+
+	InlineMsgId     string
 	CallbackMsgId   int
 	CallbackQueryId string
-	FromID          int
+	FromID          int64
 	Prefix          string
 	Text            string
 	Args            []string
+
+	errorTemplate string
+	l10n          *L10n
+	draftProvider *DraftProvider
+	payloadType   BotPayloadType
+	sceneRuntime  sceneRuntime
+
+	ctx context.Context
 }
 
+// AnswerMessage represents a message sent or edited via MsgContext.
+// It holds metadata to allow further editing or deletion.
 type AnswerMessage struct {
 	MessageID int
 	Text      string
 	IsMedia   bool
-	Keyboard  *InlineKeyboard
-	ctx       *MsgContext
+	ctx       *MsgContext // internal back-reference
 }
 
-func (ctx *MsgContext) edit(messageId int, text string, keyboard *InlineKeyboard) *AnswerMessage {
-	params := &EditMessageTextP{
-		MessageID: messageId,
-		ChatID:    ctx.Msg.Chat.ID,
+// Internal helper for text edits with optional keyboard and parse mode.
+func (ctx *MsgContext) 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.EditMessageTextP{
 		Text:      text,
-		ParseMode: 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.Api.logger.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.Api.logger.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 laniakea.EscapeMarkdownV2() before passing here.
+// Unescaped input may cause Telegram API errors or broken formatting.
+func (m *AnswerMessage) EditMarkdown(text string) *AnswerMessage {
+	return m.ctx.edit(m.MessageID, text, nil, tgapi.ParseMDV2)
+}
+
+// Internal helper for editing callback-linked messages.
+func (ctx *MsgContext) 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)
+	return ctx.edit(ctx.CallbackMsgId, text, keyboard, parseMode)
 }
+
+// EditCallback edits the callback message using plain text (ParseNone).
+func (ctx *MsgContext) EditCallback(text string, keyboard *InlineKeyboard) *AnswerMessage {
+	return ctx.editCallback(text, keyboard, tgapi.ParseNone)
+}
+
+// EditCallbackMarkdown edits the callback message using MarkdownV2.
+//
+// ⚠️ WARNING: User input must be escaped with laniakea.EscapeMarkdownV2() before passing here.
+func (ctx *MsgContext) EditCallbackMarkdown(text string, keyboard *InlineKeyboard) *AnswerMessage {
+	return ctx.editCallback(text, keyboard, tgapi.ParseMDV2)
+}
+
+// EditCallbackf formats a string using fmt.Sprintf and edits the callback message with plain text.
 func (ctx *MsgContext) EditCallbackf(format string, keyboard *InlineKeyboard, args ...any) *AnswerMessage {
-	return ctx.EditCallback(fmt.Sprintf(format, args...), keyboard)
+	return ctx.editCallback(fmt.Sprintf(format, args...), keyboard, tgapi.ParseNone)
 }
 
-func (ctx *MsgContext) editPhotoText(messageId int, text string, kb *InlineKeyboard) *AnswerMessage {
-	params := &EditMessageCaptionP{
-		ChatID:    ctx.Msg.Chat.ID,
-		MessageID: messageId,
+// EditCallbackfMarkdown formats a string using fmt.Sprintf and edits the callback message with MarkdownV2.
+//
+// ⚠️ WARNING: User input must be escaped with laniakea.EscapeMarkdownV2() before passing here.
+func (ctx *MsgContext) EditCallbackfMarkdown(format string, keyboard *InlineKeyboard, args ...any) *AnswerMessage {
+	return ctx.editCallback(fmt.Sprintf(format, args...), keyboard, tgapi.ParseMDV2)
+}
+
+// Internal helper for media-caption edits.
+func (ctx *MsgContext) 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.EditMessageCaptionP{
 		Caption:   text,
-		ParseMode: 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.Api.logger.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.Api.logger.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 := &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 laniakea.EscapeMarkdownV2() before passing here.
+func (m *AnswerMessage) EditCaptionMarkdown(text string) *AnswerMessage {
+	return m.ctx.editPhotoText(m.MessageID, text, nil, tgapi.ParseMDV2)
+}
+
+// EditCaptionKeyboard edits the caption of a media message with a new inline keyboard (plain text).
+func (m *AnswerMessage) EditCaptionKeyboard(text string, kb *InlineKeyboard) *AnswerMessage {
+	return m.ctx.editPhotoText(m.MessageID, text, kb, tgapi.ParseNone)
+}
+
+// EditCaptionKeyboardMarkdown edits the caption of a media message with a new inline keyboard using MarkdownV2.
+//
+// ⚠️ WARNING: User input must be escaped with laniakea.EscapeMarkdownV2() before passing here.
+func (m *AnswerMessage) EditCaptionKeyboardMarkdown(text string, kb *InlineKeyboard) *AnswerMessage {
+	return m.ctx.editPhotoText(m.MessageID, text, kb, tgapi.ParseMDV2)
+}
+
+// Internal helper for message replies with optional keyboard and parse mode.
+func (ctx *MsgContext) 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.SendMessageP{
 		ChatID:    ctx.Msg.Chat.ID,
 		Text:      text,
-		ParseMode: 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.Api.logger.Errorln(err)
+		ctx.Logger.Errorln(err)
 		return nil
 	}
 	return &AnswerMessage{
 		MessageID: msg.MessageID, ctx: ctx, IsMedia: false, Text: text,
 	}
 }
+
+// Answer sends a plain text message (ParseNone).
 func (ctx *MsgContext) Answer(text string) *AnswerMessage {
-	return ctx.answer(text, nil)
-}
-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)
+	return ctx.answer(text, nil, tgapi.ParseNone)
 }
 
-func (ctx *MsgContext) answerPhoto(photoId, text string, kb *InlineKeyboard) *AnswerMessage {
-	params := &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 *MsgContext) AnswerLong(text string) []*AnswerMessage {
+	return ctx.answerLong(text, nil, tgapi.ParseNone)
+}
+
+// AnswerMarkdown sends a message using MarkdownV2 formatting.
+//
+// ⚠️ WARNING: User input must be escaped with laniakea.EscapeMarkdownV2() before passing here.
+func (ctx *MsgContext) AnswerMarkdown(text string) *AnswerMessage {
+	return ctx.answer(text, nil, tgapi.ParseMDV2)
+}
+
+// Answerf formats a string using fmt.Sprintf and sends it as a plain text message.
+func (ctx *MsgContext) Answerf(template string, args ...any) *AnswerMessage {
+	return ctx.answer(fmt.Sprintf(template, args...), nil, tgapi.ParseNone)
+}
+
+// AnswerLongf formats a string using fmt.Sprintf and sends it as one or more plain-text messages.
+func (ctx *MsgContext) AnswerLongf(template string, args ...any) []*AnswerMessage {
+	return ctx.answerLong(fmt.Sprintf(template, args...), nil, tgapi.ParseNone)
+}
+
+// AnswerfMarkdown formats a string using fmt.Sprintf and sends it using MarkdownV2.
+//
+// ⚠️ WARNING: User input must be escaped with laniakea.EscapeMarkdownV2() before passing here.
+func (ctx *MsgContext) AnswerfMarkdown(template string, args ...any) *AnswerMessage {
+	return ctx.answer(fmt.Sprintf(template, args...), nil, tgapi.ParseMDV2)
+}
+
+// Keyboard sends a message with an inline keyboard (plain text).
+func (ctx *MsgContext) Keyboard(text string, kb *InlineKeyboard) *AnswerMessage {
+	return ctx.answer(text, kb, tgapi.ParseNone)
+}
+
+// KeyboardLong sends long plain text split across multiple messages.
+//
+// The inline keyboard is attached only to the final chunk.
+func (ctx *MsgContext) KeyboardLong(text string, kb *InlineKeyboard) []*AnswerMessage {
+	return ctx.answerLong(text, kb, tgapi.ParseNone)
+}
+
+// KeyboardMarkdown sends a message with an inline keyboard using MarkdownV2.
+//
+// ⚠️ WARNING: User input must be escaped with laniakea.EscapeMarkdownV2() before passing here.
+func (ctx *MsgContext) KeyboardMarkdown(text string, keyboard *InlineKeyboard) *AnswerMessage {
+	return ctx.answer(text, keyboard, tgapi.ParseMDV2)
+}
+
+func (ctx *MsgContext) 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
+}
+
+// Internal helper for photo replies with optional caption and keyboard.
+func (ctx *MsgContext) 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.SendPhotoP{
 		ChatID:    ctx.Msg.Chat.ID,
 		Caption:   text,
-		ParseMode: ParseMD,
+		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.Api.logger.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,
 	}
 }
+
+// AnswerPhoto sends a photo with plain text caption.
 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)
+	return ctx.answerPhoto(photoId, text, nil, tgapi.ParseNone)
 }
 
+// AnswerPhotoMarkdown sends a photo with MarkdownV2 caption.
+//
+// ⚠️ WARNING: User input must be escaped with laniakea.EscapeMarkdownV2() before passing here.
+func (ctx *MsgContext) AnswerPhotoMarkdown(photoId, text string) *AnswerMessage {
+	return ctx.answerPhoto(photoId, text, nil, tgapi.ParseMDV2)
+}
+
+// AnswerPhotoKeyboard sends a photo with caption and inline keyboard (plain text).
+func (ctx *MsgContext) AnswerPhotoKeyboard(photoId, text string, kb *InlineKeyboard) *AnswerMessage {
+	return ctx.answerPhoto(photoId, text, kb, tgapi.ParseNone)
+}
+
+// AnswerPhotoKeyboardMarkdown sends a photo with caption and inline keyboard using MarkdownV2.
+//
+// ⚠️ WARNING: User input must be escaped with laniakea.EscapeMarkdownV2() before passing here.
+func (ctx *MsgContext) AnswerPhotoKeyboardMarkdown(photoId, text string, kb *InlineKeyboard) *AnswerMessage {
+	return ctx.answerPhoto(photoId, text, kb, tgapi.ParseMDV2)
+}
+
+// AnswerPhotof formats a string and sends it as a photo caption (plain text).
+func (ctx *MsgContext) AnswerPhotof(photoId, template string, args ...any) *AnswerMessage {
+	return ctx.answerPhoto(photoId, fmt.Sprintf(template, args...), nil, tgapi.ParseNone)
+}
+
+// AnswerPhotofMarkdown formats a string and sends it as a photo caption using MarkdownV2.
+//
+// ⚠️ WARNING: User input must be escaped with laniakea.EscapeMarkdownV2() before passing here.
+func (ctx *MsgContext) AnswerPhotofMarkdown(photoId, template string, args ...any) *AnswerMessage {
+	return ctx.answerPhoto(photoId, fmt.Sprintf(template, args...), nil, tgapi.ParseMDV2)
+}
+
+// Internal helper that deletes a message by ID.
 func (ctx *MsgContext) delete(messageId int) {
-	_, err := ctx.Api.DeleteMessage(&DeleteMessageP{
+	if messageId == 0 {
+		ctx.Logger.Errorln(ErrMessageIDZero)
+		return
+	}
+	if ctx.Msg == nil {
+		ctx.Logger.Errorln(ErrMessageContextNil)
+		return
+	}
+	_, err := ctx.Api.DeleteMessageWithContext(ctx.Context(), tgapi.DeleteMessageP{
 		ChatID:    ctx.Msg.Chat.ID,
 		MessageID: messageId,
 	})
 	if err != nil {
-		ctx.Api.logger.Errorln(err)
+		ctx.Logger.Errorln(err)
 	}
 }
-func (m *AnswerMessage) Delete() {
-	m.ctx.delete(m.MessageID)
-}
+
+// Delete removes the message associated with this AnswerMessage.
+func (m *AnswerMessage) Delete() { m.ctx.delete(m.MessageID) }
+
+// CallbackDelete deletes the message that triggered the callback query.
 func (ctx *MsgContext) CallbackDelete() {
+	if ctx.CallbackMsgId == 0 {
+		ctx.Logger.Errorln(ErrCallbackMessageMissing)
+		return
+	}
 	ctx.delete(ctx.CallbackMsgId)
 }
 
+// Internal helper that answers a callback query with optional text, alert, or URL.
 func (ctx *MsgContext) answerCallbackQuery(url, text string, showAlert bool) {
 	if len(ctx.CallbackQueryId) == 0 {
 		return
 	}
-	_, err := ctx.Api.AnswerCallbackQuery(&AnswerCallbackQueryP{
+	_, err := ctx.Api.AnswerCallbackQueryWithContext(ctx.Context(), tgapi.AnswerCallbackQueryP{
 		CallbackQueryID: ctx.CallbackQueryId,
 		Text:            text, ShowAlert: showAlert, URL: url,
 	})
 	if err != nil {
-		ctx.Api.logger.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 ChatActions) {
-	_, err := ctx.Api.SendChatAction(SendChatActionP{
+// AnswerCbQuery answers the callback query with no text or alert.
+func (ctx *MsgContext) AnswerCbQuery() { ctx.answerCallbackQuery("", "", false) }
+
+// AnswerCbQueryText answers the callback query with a text notification.
+func (ctx *MsgContext) AnswerCbQueryText(text string) { ctx.answerCallbackQuery("", text, false) }
+
+// AnswerCbQueryAlert answers the callback query with a user-visible alert.
+func (ctx *MsgContext) AnswerCbQueryAlert(text string) { ctx.answerCallbackQuery("", text, true) }
+
+// AnswerCbQueryUrl answers the callback query with a URL redirect.
+func (ctx *MsgContext) AnswerCbQueryUrl(u string) { ctx.answerCallbackQuery(u, "", false) }
+
+// SendAction sends a chat action (typing, uploading_photo, etc.) to indicate bot activity.
+func (ctx *MsgContext) SendAction(action tgapi.ChatActionType) {
+	if ctx.Msg == nil {
+		ctx.Logger.Errorln("Can't send action without chat message context")
+		return
+	}
+	params := tgapi.SendChatActionP{
 		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.Api.logger.Errorln(err)
+		ctx.Logger.Errorln(err)
 	}
 }
 
+// Internal helper that formats, sends, and logs an error.
 func (ctx *MsgContext) error(err error) {
-	text := fmt.Sprintf(ctx.Bot.errorTemplate, EscapeMarkdown(err.Error()))
+	text := fmt.Sprintf(ctx.errorTemplate, err.Error())
 
 	if ctx.CallbackQueryId != "" {
 		ctx.answerCallbackQuery("", text, false)
 	} else {
-		ctx.answer(text, nil)
+		ctx.answer(text, nil, tgapi.ParseNone)
 	}
-	ctx.Bot.logger.Errorln(err)
+	ctx.Logger.Errorln(err)
 }
-func (ctx *MsgContext) Error(err error) {
-	ctx.error(err)
+
+// Error is an alias for error().
+func (ctx *MsgContext) Error(err error) { ctx.error(err) }
+
+func (ctx *MsgContext) 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
+	}
+
+	if ctx.Api.Limiter != nil {
+		c, cancel := context.WithTimeout(ctx.Context(), 5*time.Second)
+		defer cancel()
+		if err := ctx.Api.Limiter.Wait(c, ctx.Msg.Chat.ID); err != nil {
+			ctx.Logger.Errorln(err)
+			return nil
+		}
+	}
+
+	draft := ctx.draftProvider.NewDraft(parseMode).SetChat(ctx.Msg.Chat.ID, ctx.Msg.MessageThreadID)
+	return draft
+}
+
+// NewDraft creates a new message draft associated with the current chat.
+// Uses the API limiter to avoid rate limiting.
+func (ctx *MsgContext) NewDraft() *Draft {
+	return ctx.newDraft(tgapi.ParseNone)
+}
+
+// NewDraftMarkdown creates a new message draft associated with the current chat,
+// with Markdown V2 parse mode enabled.
+// Uses the API limiter to avoid rate limiting.
+func (ctx *MsgContext) NewDraftMarkdown() *Draft {
+	return ctx.newDraft(tgapi.ParseMDV2)
+}
+
+// Translate looks up a key in the current user's language.
+// Falls back to the bot's default language if user's language is unknown or unsupported.
+func (ctx *MsgContext) Translate(key string) string {
+	if ctx.From == nil {
+		return key
+	}
+	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 *MsgContext) NewInlineKeyboard(maxRow int) *InlineKeyboard {
+	return NewInlineKeyboard(ctx.payloadType, maxRow)
+}
+
+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 *MsgContext) BindArgs(dst any) error {
+	return bindPositional(ctx.Args, dst)
+}
+
+// Context returns the request-scoped context associated with the current update.
+func (ctx *MsgContext) Context() context.Context {
+	if ctx.ctx == nil {
+		return context.Background()
+	}
+	return ctx.ctx
+}
+
+// EnterScene enters the named scene at its configured entry step.
+func (ctx *MsgContext) EnterScene(name string) error {
+	if ctx.sceneRuntime == nil {
+		return ErrSceneRuntimeNil
+	}
+
+	scene, ok := ctx.sceneRuntime.findScene(name)
+	if !ok {
+		return ErrSceneNotFound
+	}
+
+	key, ok := ctx.sceneRuntime.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 *MsgContext) 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 := ctx.sceneRuntime.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 *MsgContext) 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 := ctx.sceneRuntime.buildSceneKey(scene.Scope, ctx)
+	if !ok {
+		return ErrCantFindSession
+	}
+
+	return ctx.sceneRuntime.deleteSession(key)
 }

msg_context_test.go

@@ -0,0 +1,310 @@
+package laniakea
+
+import (
+	"encoding/json"
+	"errors"
+	"io"
+	"net/http"
+	"reflect"
+	"strings"
+	"testing"
+
+	"git.scuroneko.dev/scuroneko/laniakea/tgapi"
+	"git.scuroneko.dev/scuroneko/slog"
+)
+
+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 := &MsgContext{
+		Api: api,
+		Msg: &tgapi.Message{
+			Chat:               &tgapi.Chat{ID: 42, Type: string(tgapi.ChatTypePrivate)},
+			DirectMessageTopic: &tgapi.DirectMessageTopic{TopicID: 77},
+		},
+		Logger: slog.CreateLogger(),
+	}
+
+	answer := ctx.AnswerPhoto("photo-id", "caption")
+	if answer == nil {
+		t.Fatal("expected answer message")
+	}
+	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 := &MsgContext{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 TestBindArgsLeavesTrailingFieldsZeroWhenArgsRunOut(t *testing.T) {
+	type input struct {
+		ID     int
+		Reason string
+		Admin  bool
+	}
+
+	ctx := &MsgContext{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 := &MsgContext{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 := &MsgContext{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 := &MsgContext{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 TestAnswerRejectsEmptyMessage(t *testing.T) {
+	ctx := &MsgContext{
+		Msg:    &tgapi.Message{Chat: &tgapi.Chat{ID: 42, Type: string(tgapi.ChatTypePrivate)}},
+		Logger: slog.CreateLogger(),
+	}
+
+	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 := &MsgContext{
+		Api:    api,
+		Msg:    &tgapi.Message{Chat: &tgapi.Chat{ID: 42, Type: string(tgapi.ChatTypePrivate)}},
+		Logger: slog.CreateLogger(),
+	}
+
+	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 := &MsgContext{
+		Api:    api,
+		Msg:    &tgapi.Message{Chat: &tgapi.Chat{ID: 42, Type: string(tgapi.ChatTypePrivate)}},
+		Logger: slog.CreateLogger(),
+	}
+	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)
+	}
+}

multipart.go

@@ -1,131 +0,0 @@
-package laniakea
-
-import (
-	"encoding/json"
-	"fmt"
-	"io"
-	"mime/multipart"
-	"reflect"
-	"slices"
-	"strconv"
-	"strings"
-)
-
-func Encode[T any](w *multipart.Writer, req T) error {
-	v := reflect.ValueOf(req)
-	if v.Kind() == reflect.Ptr {
-		v = v.Elem()
-	}
-
-	if v.Kind() != reflect.Struct {
-		return fmt.Errorf("req must be a struct")
-	}
-
-	t := v.Type()
-	for i := 0; i < v.NumField(); i++ {
-		field := v.Field(i)
-		fieldType := t.Field(i)
-
-		formTags := strings.Split(fieldType.Tag.Get("json"), ",")
-		fieldName := ""
-		if len(formTags) == 0 {
-			formTags = strings.Split(fieldType.Tag.Get("json"), ",")
-		}
-
-		if len(formTags) > 0 {
-			fieldName = formTags[0]
-			if fieldName == "-" {
-				continue
-			}
-			if slices.Index(formTags, "omitempty") >= 0 {
-				if field.IsZero() {
-					continue
-				}
-			}
-		} else {
-			fieldName = strings.ToLower(fieldType.Name)
-		}
-
-		var (
-			fw  io.Writer
-			err error
-		)
-		switch field.Kind() {
-		case reflect.String:
-			if field.String() != "" {
-				fw, err = w.CreateFormField(fieldName)
-				if err == nil {
-					_, err = fw.Write([]byte(field.String()))
-				}
-			}
-		case reflect.Int, reflect.Int8, reflect.Int16, reflect.Int32, reflect.Int64:
-			fw, err = w.CreateFormField(fieldName)
-			if err == nil {
-				_, err = fw.Write([]byte(strconv.FormatInt(field.Int(), 10)))
-			}
-		case reflect.Uint, reflect.Uint8, reflect.Uint16, reflect.Uint32, reflect.Uint64:
-			fw, err = w.CreateFormField(fieldName)
-			if err == nil {
-				_, err = fw.Write([]byte(strconv.FormatUint(field.Uint(), 10)))
-			}
-		case reflect.Float32, reflect.Float64:
-			fw, err = w.CreateFormField(fieldName)
-			if err == nil {
-				_, err = fw.Write([]byte(strconv.FormatFloat(field.Float(), 'f', -1, 64)))
-			}
-		case reflect.Bool:
-			fw, err = w.CreateFormField(fieldName)
-			if err == nil {
-				_, err = fw.Write([]byte(strconv.FormatBool(field.Bool())))
-			}
-
-		case reflect.Slice:
-			if field.Type().Elem().Kind() == reflect.Uint8 && !field.IsNil() {
-				filename := fieldType.Tag.Get("filename")
-				if filename == "" {
-					filename = fieldName
-				}
-
-				ext := ""
-				filename = filename + ext
-
-				fw, err = w.CreateFormFile(fieldName, filename)
-				if err == nil {
-					_, err = fw.Write(field.Bytes())
-				}
-			} else if !field.IsNil() {
-				// Handle slice of primitive values (as multiple form fields with the same name)
-				for j := 0; j < field.Len(); j++ {
-					elem := field.Index(j)
-					fw, err = w.CreateFormField(fieldName)
-					if err == nil {
-						switch elem.Kind() {
-						case reflect.String:
-							_, err = fw.Write([]byte(elem.String()))
-						case reflect.Int, reflect.Int8, reflect.Int16, reflect.Int32, reflect.Int64:
-							_, err = fw.Write([]byte(strconv.FormatInt(elem.Int(), 10)))
-						case reflect.Uint, reflect.Uint8, reflect.Uint16, reflect.Uint32, reflect.Uint64:
-							_, err = fw.Write([]byte(strconv.FormatUint(elem.Uint(), 10)))
-						}
-					}
-				}
-			}
-
-		case reflect.Struct:
-			var jsonData []byte
-			jsonData, err = json.Marshal(field.Interface())
-			if err == nil {
-				fw, err = w.CreateFormField(fieldName)
-				if err == nil {
-					_, err = fw.Write(jsonData)
-				}
-			}
-		}
-
-		if err != nil {
-			return err
-		}
-	}
-
-	return nil
-}

plugins.go

@@ -1,84 +1,370 @@
 package laniakea
 
 import (
-	"log"
+	"errors"
+	"regexp"
 
-	"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/slog"
 )
 
-type CommandExecutor func(ctx *MsgContext, dbContext *DatabaseContext)
+// CommandValueType defines the expected type of command argument.
+type CommandValueType string
 
-type PluginBuilder struct {
-	name           string
-	commands       map[string]*CommandExecutor
-	payloads       map[string]*CommandExecutor
-	updateListener *CommandExecutor
-	middlewares    extypes.Slice[*PluginMiddleware]
+const (
+	// CommandValueStringType expects any non-empty string.
+	CommandValueStringType CommandValueType = "string"
+	// CommandValueIntType expects a decimal integer (digits only).
+	CommandValueIntType CommandValueType = "int"
+	// CommandValueBoolType is reserved for future use (not implemented).
+	CommandValueBoolType CommandValueType = "bool"
+	// CommandValueAnyType accepts any input without validation.
+	CommandValueAnyType CommandValueType = "any"
+)
+
+var (
+	// CommandRegexInt matches one or more digits.
+	CommandRegexInt = regexp.MustCompile(`^\d+$`)
+	// CommandRegexString matches any non-empty string.
+	CommandRegexString = regexp.MustCompile(`^.+$`)
+	// CommandRegexBool matches true or false.
+	CommandRegexBool = regexp.MustCompile(`^(true|false)$`)
+)
+
+// ErrCmdArgCountMismatch is returned when the number of provided arguments
+// is less than the number of required arguments.
+var ErrCmdArgCountMismatch = errors.New("command arg count mismatch")
+
+// ErrCmdArgRegexpMismatch is returned when an argument fails regex validation.
+var ErrCmdArgRegexpMismatch = errors.New("command arg regexp mismatch")
+
+// CommandArg defines a single argument for a command, including type, regex,
+// and whether it is required.
+type CommandArg struct {
+	valueType CommandValueType // Type of expected value
+	text      string           // Human-readable description (not used in validation)
+	regex     *regexp.Regexp   // Regex used to validate input
+	required  bool             // Whether this argument must be provided
 }
 
-type Plugin struct {
-	Name           string
-	Commands       map[string]*CommandExecutor
-	Payloads       map[string]*CommandExecutor
-	UpdateListener *CommandExecutor
-	Middlewares    extypes.Slice[*PluginMiddleware]
+// NewCommandArg creates a new CommandArg with the given text and type.
+// Uses a default regex based on the type (string or int).
+// For CommandValueAnyType, no validation is performed.
+func NewCommandArg(text string) CommandArg {
+	return CommandArg{CommandValueAnyType, text, CommandRegexString, false}
 }
 
-func NewPlugin(name string) *PluginBuilder {
-	return &PluginBuilder{
-		name:     name,
-		commands: make(map[string]*CommandExecutor),
-		payloads: make(map[string]*CommandExecutor),
+// SetValueType sets expected value type and switches built-in validation regexp.
+func (c CommandArg) SetValueType(t CommandValueType) CommandArg {
+	regex := CommandRegexString
+	switch t {
+	case CommandValueIntType:
+		regex = CommandRegexInt
+	case CommandValueBoolType:
+		regex = CommandRegexBool
+	case CommandValueAnyType:
+		regex = nil // Skip validation
+	}
+	c.valueType = t
+	c.regex = regex
+	return c
+}
+
+// SetRequired marks this argument as required.
+// Returns the receiver for method chaining.
+func (c CommandArg) SetRequired() CommandArg {
+	c.required = true
+	return c
+}
+
+// CommandExecutor is the function type that executes a command.
+// It receives the message context and a database context (generic).
+// Returning a non-nil error routes it through the bot's error handler.
+type CommandExecutor[T DbContext] func(ctx *MsgContext, 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 DbContext] struct {
+	command     string                       // The command trigger (e.g., "/start")
+	description string                       // Human-readable description for help
+	exec        CommandExecutor[T]           // Function to execute when command is triggered
+	args        extypes.Slice[CommandArg]    // List of expected arguments
+	middlewares extypes.Slice[Middleware[T]] // Optional middleware chain
+	skipAutoCmd bool                         // If true, this command won't be auto-added to help menus
+}
+
+// NewCommand creates a new Command with the given executor, command string, and arguments.
+// The command string should not include the leading slash (e.g., "start", not "/start").
+func NewCommand[T any](exec CommandExecutor[T], command string, args ...CommandArg) *Command[T] {
+	return &Command[T]{command, "", exec, args, make(extypes.Slice[Middleware[T]], 0), false}
+}
+
+// NewPayload creates a new Command with the given executor, command payload string, and arguments.
+// The command string can contain any symbols, but it is recommended to use only "_", "-", ".", a-z, A-Z, and 0-9.
+func NewPayload[T any](exec CommandExecutor[T], command string, args ...CommandArg) *Command[T] {
+	return &Command[T]{command, "", exec, args, make(extypes.Slice[Middleware[T]], 0), false}
+}
+
+// Use adds a middleware to the command's execution chain.
+// Middlewares are executed in the order they are added.
+func (c *Command[T]) Use(m Middleware[T]) *Command[T] {
+	c.middlewares = c.middlewares.Push(m)
+	return c
+}
+
+// SetDescription sets the human-readable description of the command.
+func (c *Command[T]) SetDescription(desc string) *Command[T] {
+	c.description = desc
+	return c
+}
+
+// SkipCommandAutoGen marks this command to be excluded from auto-generated help menus.
+func (c *Command[T]) SkipCommandAutoGen() *Command[T] {
+	c.skipAutoCmd = true
+	return c
+}
+
+// Internal helper that validates provided command arguments.
+func (c *Command[T]) validateArgs(args []string) error {
+	for i := range c.args.Len() {
+		if i >= len(args) && c.args.Get(i).required {
+			return ErrCmdArgCountMismatch
+		}
+	}
+
+	// Validate each argument against its regex
+	for i, arg := range args {
+		if i >= c.args.Len() {
+			// Extra arguments beyond defined args are ignored
+			break
+		}
+		cmdArg := c.args.Get(i)
+		if cmdArg.regex == nil {
+			continue // Skip validation for CommandValueAnyType
+		}
+		if !cmdArg.regex.MatchString(arg) {
+			return ErrCmdArgRegexpMismatch
+		}
+	}
+	return nil
+}
+
+// Plugin represents a collection of commands and payloads (e.g., callback handlers),
+// with shared middleware and configuration.
+//
+// A Plugin is intended to be fully configured before it is passed to Bot.AddPlugins.
+// After registration, treat the plugin as committed and do not mutate it further.
+// Post-registration changes through the original *Plugin are not a supported API.
+type Plugin[T DbContext] struct {
+	name        string                       // Name of the plugin (e.g., "admin", "user")
+	commands    map[string]*Command[T]       // Registered commands (triggered by message)
+	payloads    map[string]*Command[T]       // Registered payloads (triggered by callback data)
+	scenes      map[string]*Scene[T]         // Optional scenes for multi-step interactions
+	middlewares extypes.Slice[Middleware[T]] // Shared middlewares for all commands/payloads
+	skipAutoCmd bool                         // If true, all commands in this plugin are excluded from auto-help
+	logger      *slog.Logger
+
+	handlers map[tgapi.UpdateType]CommandExecutor[T]
+
+	onClose func() error
+}
+
+// NewPlugin creates a new Plugin with the given name.
+func NewPlugin[T DbContext](name string) *Plugin[T] {
+	return &Plugin[T]{
+		name:        name,
+		commands:    make(map[string]*Command[T]),
+		payloads:    make(map[string]*Command[T]),
+		middlewares: make(extypes.Slice[Middleware[T]], 0),
+		scenes:      make(map[string]*Scene[T]),
+		skipAutoCmd: false,
+		logger:      nil,
+		handlers:    make(map[tgapi.UpdateType]CommandExecutor[T]),
 	}
 }
 
-func (p *PluginBuilder) Command(f CommandExecutor, cmd ...string) *PluginBuilder {
-	for _, c := range cmd {
-		p.commands[c] = &f
+// AddCommand registers a command in the plugin.
+// The command's .command field is used as the key.
+func (p *Plugin[T]) AddCommand(command *Command[T]) *Plugin[T] {
+	p.commands[command.command] = command
+	return p
+}
+
+// NewCommand creates and immediately adds a new command to the plugin.
+// Returns the created command for further configuration.
+func (p *Plugin[T]) NewCommand(exec CommandExecutor[T], command string, args ...CommandArg) *Command[T] {
+	cmd := NewCommand(exec, command, args...)
+	p.AddCommand(cmd)
+	return cmd
+}
+
+// AddPayload registers a payload (e.g., callback query data) in the plugin.
+// Payloads are triggered by inline button callback_data, not by message text.
+func (p *Plugin[T]) AddPayload(command *Command[T]) *Plugin[T] {
+	p.payloads[command.command] = command
+	return p
+}
+
+// NewPayload creates and immediately adds a new payload command to the plugin.
+// Returns the created payload command for further configuration.
+func (p *Plugin[T]) NewPayload(exec CommandExecutor[T], command string, args ...CommandArg) *Command[T] {
+	cmd := NewPayload(exec, command, args...)
+	p.AddPayload(cmd)
+	return cmd
+}
+
+// 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
+	scene.setPluginName(p.name)
+	p.scenes[scene.Name] = scene
 	return p
 }
 
-func (p *PluginBuilder) Payload(f CommandExecutor, payloads ...string) *PluginBuilder {
-	for _, payload := range payloads {
-		p.payloads[payload] = &f
+// NewScene creates, registers, and returns a new scene owned by the plugin.
+func (p *Plugin[T]) NewScene(name string) *Scene[T] {
+	scene := NewScene[T](name)
+	scene.setPluginName(p.name)
+	p.AddScene(scene)
+	return scene
+}
+
+// AddUpdateHandler registers a handler for a non-command update type.
+// Message, channel post, and callback query updates stay on the command/payload flow.
+func (p *Plugin[T]) AddUpdateHandler(t tgapi.UpdateType, handler CommandExecutor[T]) *Plugin[T] {
+	switch t {
+	case tgapi.UpdateTypeMessage, tgapi.UpdateTypeChannelPost, tgapi.UpdateTypeCallbackQuery:
+		if p.logger == nil {
+			logger := utils.CreateLogger(p.name, utils.GetLoggerLevel())
+			logger.Warnf("%s can't be registred through AddUpdateHandler. Use AddPayload/NewPayload or AddCommand/NewCommand", t)
+			_ = logger.Close()
+			return p
+		}
+		p.logger.Warnf("%s can't be registred through AddUpdateHandler. Use AddPayload/NewPayload or AddCommand/NewCommand", t)
+		return p
 	}
+	p.handlers[t] = handler
 	return p
 }
 
-func (p *PluginBuilder) UpdateListener(listener CommandExecutor) *PluginBuilder {
-	p.updateListener = &listener
-	return p
-}
-
-func (p *PluginBuilder) Middleware(middleware *PluginMiddleware) *PluginBuilder {
+// 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
 }
 
-func (p *PluginBuilder) Build() Plugin {
-	if len(p.commands) == 0 && len(p.payloads) == 0 {
-		log.Printf("no command or payloads for %s", p.name)
+// 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 *slog.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
+}
+
+// Close releases plugin-owned resources such as its logger and optional
+// OnClose callback.
+func (p *Plugin[T]) Close() error {
+	var e []error
+	if p.logger != nil {
+		if err := p.logger.Close(); err != nil {
+			e = append(e, err)
+		}
 	}
-	return Plugin{
-		Name:           p.name,
-		Commands:       p.commands,
-		Payloads:       p.payloads,
-		UpdateListener: p.updateListener,
-		Middlewares:    p.middlewares,
+	if p.onClose != nil {
+		if err := p.onClose(); err != nil {
+			e = append(e, err)
+		}
+	}
+	return errors.Join(e...)
+}
+
+// Internal helper that validates and executes a command handler.
+func (p *Plugin[T]) executeCmd(cmd string, ctx *MsgContext, db T) {
+	command, exists := p.commands[cmd]
+	if !exists {
+		ctx.error(errors.New("command not found"))
+		return
+	}
+
+	if err := command.validateArgs(ctx.Args); err != nil {
+		ctx.error(err)
+		return
+	}
+
+	// Run command-specific middlewares
+	for _, m := range command.middlewares {
+		if !m.Execute(ctx, db) {
+			return
+		}
+	}
+
+	// Execute command
+	if err := command.exec(ctx, db); err != nil {
+		ctx.error(err)
 	}
 }
 
-func (p *Plugin) Execute(cmd string, ctx *MsgContext, dbContext *DatabaseContext) {
-	(*p.Commands[cmd])(ctx, dbContext)
+// Internal helper that validates and executes a payload handler.
+func (p *Plugin[T]) executePayload(payload string, ctx *MsgContext, db T) {
+	command, exists := p.payloads[payload]
+	if !exists {
+		ctx.error(errors.New("payload not found"))
+		return
+	}
+
+	if err := command.validateArgs(ctx.Args); err != nil {
+		ctx.error(err)
+		return
+	}
+
+	// Run command-specific middlewares
+	for _, m := range command.middlewares {
+		if !m.Execute(ctx, db) {
+			return
+		}
+	}
+
+	// Execute payload
+	if err := command.exec(ctx, db); err != nil {
+		ctx.error(err)
+	}
 }
 
-func (p *Plugin) ExecutePayload(payload string, ctx *MsgContext, dbContext *DatabaseContext) {
-	(*p.Payloads[payload])(ctx, dbContext)
-}
-
-func (p *Plugin) executeMiddlewares(ctx *MsgContext, db *DatabaseContext) bool {
-	for _, m := range p.Middlewares {
+// Internal helper that runs plugin middlewares in order.
+func (p *Plugin[T]) executeMiddlewares(ctx *MsgContext, db T) bool {
+	for _, m := range p.middlewares {
 		if !m.Execute(ctx, db) {
 			return false
 		}
@@ -86,82 +372,47 @@ func (p *Plugin) executeMiddlewares(ctx *MsgContext, db *DatabaseContext) bool {
 	return true
 }
 
-type Middleware struct {
-	Name     string
-	Executor CommandExecutor
-	Order    int
-	Async    bool
-}
-type MiddlewareBuilder struct {
-	name     string
-	executor CommandExecutor
-	order    int
-	async    bool
+// MiddlewareExecutor is the function type for middleware logic.
+// Returns true to continue execution, false to block it.
+// If async, return value is ignored.
+type MiddlewareExecutor[T DbContext] func(ctx *MsgContext, db T) bool
+
+// Middleware represents a reusable execution interceptor.
+// Can be synchronous (blocking) or asynchronous (non-blocking).
+type Middleware[T DbContext] struct {
+	name     string                // Human-readable name for logging/debugging
+	executor MiddlewareExecutor[T] // Function to execute
+	order    int                   // Optional sort order (not used yet)
+	async    bool                  // If true, runs in goroutine and doesn't block
 }
 
-func NewMiddleware(name string, executor CommandExecutor) *MiddlewareBuilder {
-	return &MiddlewareBuilder{name: name, executor: executor, order: 0, async: false}
+// NewMiddleware creates a new synchronous middleware.
+func NewMiddleware[T DbContext](name string, executor MiddlewareExecutor[T]) Middleware[T] {
+	return Middleware[T]{name, executor, 0, false}
 }
-func (m *MiddlewareBuilder) SetName(name string) *MiddlewareBuilder {
-	m.name = name
-	return m
-}
-func (m *MiddlewareBuilder) SetExecutor(executor CommandExecutor) *MiddlewareBuilder {
-	m.executor = executor
-	return m
-}
-func (m *MiddlewareBuilder) SetOrder(order int) *MiddlewareBuilder {
+
+// SetOrder sets the execution order (currently ignored).
+func (m Middleware[T]) SetOrder(order int) Middleware[T] {
 	m.order = order
 	return m
 }
-func (m *MiddlewareBuilder) SetAsync(async bool) *MiddlewareBuilder {
+
+// 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 *MiddlewareBuilder) Build() Middleware {
-	return Middleware{
-		Name:     m.name,
-		Executor: m.executor,
-		Order:    m.order,
-		Async:    m.async,
-	}
-}
-func (m Middleware) Execute(ctx *MsgContext, db *DatabaseContext) {
-	if m.Async {
-		go m.Executor(ctx, db)
-	} else {
-		m.Execute(ctx, db)
-	}
-}
 
-type PluginMiddlewareExecutor func(ctx *MsgContext, db *DatabaseContext) bool
-
-// PluginMiddleware
-// When async, returned value ignored
-type PluginMiddleware struct {
-	executor PluginMiddlewareExecutor
-	order    int
-	async    bool
-}
-
-func NewPluginMiddleware(executor PluginMiddlewareExecutor) *PluginMiddleware {
-	return &PluginMiddleware{
-		executor: executor,
-		order:    0,
-		async:    false,
-	}
-}
-func (m *PluginMiddleware) SetOrder(order int) *PluginMiddleware {
-	m.order = order
-	return m
-}
-func (m *PluginMiddleware) SetAsync(async bool) *PluginMiddleware {
-	m.async = async
-	return m
-}
-func (m *PluginMiddleware) Execute(ctx *MsgContext, db *DatabaseContext) bool {
+// Execute runs the middleware.
+// If async, runs in a goroutine and returns true immediately.
+// Otherwise, returns the result of the executor.
+func (m Middleware[T]) Execute(ctx *MsgContext, db T) bool {
 	if m.async {
-		go m.executor(ctx, db)
+		ctx := *ctx // copy context to avoid race condition
+		go func(ctx MsgContext) {
+			m.executor(&ctx, db)
+		}(ctx)
 		return true
 	}
 	return m.executor(ctx, db)

plugins_test.go

@@ -0,0 +1,40 @@
+package laniakea
+
+import (
+	"errors"
+	"testing"
+)
+
+func TestValidateArgsRequiresFullMatch(t *testing.T) {
+	intCmd := NewCommand[NoDB](func(ctx *MsgContext, db NoDB) error { return nil }, "int", NewCommandArg("n").SetValueType(CommandValueIntType).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[NoDB](func(ctx *MsgContext, db NoDB) error { return nil }, "bool", NewCommandArg("flag").SetValueType(CommandValueBoolType).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[NoDB](
+		func(ctx *MsgContext, db NoDB) error { return nil },
+		"mixed",
+		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)
+	}
+}

runners.go

@@ -1,85 +1,148 @@
 package laniakea
 
 import (
+	"context"
 	"time"
 )
 
-type RunnerFn func(*Bot) error
-type RunnerBuilder struct {
-	name    string
-	onetime bool
-	async   bool
-	timeout time.Duration
-	fn      RunnerFn
-}
-type Runner struct {
-	Name    string
-	Onetime bool
-	Async   bool
-	Timeout time.Duration
-	Fn      RunnerFn
+// RunnerFn is the function type for a runner. It receives a pointer to
+// the Bot and returns an error if execution fails.
+type RunnerFn[T DbContext] func(*Bot[T]) error
+
+// Runner represents a configurable background or one-time task to be
+// executed by a Bot.
+//
+// Runners are configured using builder methods: Onetime(), Async(), Timeout().
+// Once Execute() is called, the Runner should not be modified.
+//
+// Execution semantics:
+//   - onetime=true, async=false: Run once synchronously (blocks).
+//   - onetime=true, async=true:  Run once in a goroutine (non-blocking).
+//   - onetime=false, async=true: Run repeatedly in a goroutine with timeout.
+//   - onetime=false, async=false: Invalid configuration — ignored with warning.
+type Runner[T DbContext] struct {
+	name    string        // Human-readable name for logging
+	onetime bool          // If true, runs once; if false, runs periodically
+	async   bool          // If true, runs in a goroutine; else, runs synchronously
+	timeout time.Duration // Duration to wait between periodic executions (ignored if onetime=true)
+	fn      RunnerFn[T]   // The function to execute
 }
 
-func NewRunner(name string, fn RunnerFn) *RunnerBuilder {
-	return &RunnerBuilder{
-		name: name, fn: fn, async: true,
-	}
-}
-func (b *RunnerBuilder) Onetime(onetime bool) *RunnerBuilder {
-	b.onetime = onetime
-	return b
-}
-func (b *RunnerBuilder) Async(async bool) *RunnerBuilder {
-	b.async = async
-	return b
-}
-func (b *RunnerBuilder) Timeout(timeout time.Duration) *RunnerBuilder {
-	b.timeout = timeout
-	return b
-}
-func (b *RunnerBuilder) Build() Runner {
-	return Runner{
-		Name: b.name, Onetime: b.onetime, Async: b.async, Fn: b.fn, Timeout: b.timeout,
+// NewRunner creates a new Runner with the given name and function.
+// By default, the Runner is configured as async=true (non-blocking).
+//
+// Builder methods (Onetime, Async, Timeout) can be chained to customize behavior.
+// DO NOT call builder methods concurrently or after Execute().
+func NewRunner[T DbContext](name string, fn RunnerFn[T]) Runner[T] {
+	return Runner[T]{
+		name:    name,
+		fn:      fn,
+		async:   true, // Default: run asynchronously
+		timeout: 0,    // Default: no timeout (ignored if onetime=true)
 	}
 }
 
-func (b *Bot) ExecRunners() {
-	for _, runner := range b.runners {
-		if !runner.Onetime && !runner.Async {
-			b.logger.Warnf("Runner %s not onetime, but sync\n", runner.Name)
+// Onetime sets whether the runner executes once or repeatedly.
+// If true, the runner runs only once.
+// If false, the runner runs in a loop with the configured timeout.
+func (r Runner[T]) Onetime(onetime bool) Runner[T] {
+	r.onetime = onetime
+	return r
+}
+
+// Async sets whether the runner executes synchronously or asynchronously.
+// If true, the runner runs in a goroutine (non-blocking).
+// If false, the runner blocks the caller during execution.
+//
+// Note: If onetime=false and async=false, the runner will be skipped with a warning.
+func (r Runner[T]) Async(async bool) Runner[T] {
+	r.async = async
+	return r
+}
+
+// Timeout sets the duration to wait between repeated executions for
+// non-onetime runners.
+//
+// If onetime=true, this value is ignored.
+// If onetime=false and async=true, this timeout determines the sleep interval
+// between loop iterations.
+//
+// A zero value (time.Duration(0)) is allowed but may trigger a warning
+// if used with a background (non-onetime) async runner.
+func (r Runner[T]) Timeout(timeout time.Duration) Runner[T] {
+	r.timeout = timeout
+	return r
+}
+
+// ExecRunners executes all runners registered on the Bot with context-based lifecycle management.
+//
+// It logs warnings for misconfigured runners:
+//   - Sync, non-onetime runners are skipped (invalid configuration).
+//   - Background (non-onetime, async) runners without a timeout trigger a warning.
+//
+// Execution logic:
+//   - onetime + async: Runs once in a goroutine.
+//   - onetime + sync:  Runs once synchronously; warns if slower than 2 seconds.
+//   - !onetime + async: Runs in a loop with timeout between iterations until ctx.Done().
+//   - !onetime + sync: Skipped with warning.
+//
+// Background runners listen for ctx.Done() and gracefully shut down when the context is canceled.
+//
+// This method is typically called once during bot startup in RunWithContext.
+func (bot *Bot[T]) ExecRunners(ctx context.Context) {
+	bot.logger.Infoln("Executing runners...")
+	for _, runner := range bot.runners {
+		// Validate configuration
+		if !runner.onetime && !runner.async {
+			bot.logger.Warnf("Runner %s not onetime, but sync — skipping\n", runner.name)
 			continue
 		}
-		if !runner.Onetime && runner.Async && runner.Timeout == (time.Second*0) {
-			b.logger.Warnf("Background runner \"%s\" should have timeout", runner.Name)
+		if !runner.onetime && runner.async && runner.timeout == 0 {
+			bot.logger.Warnf("Background runner \"%s\" has no timeout — skipping\n", runner.name)
+			continue
 		}
 
-		if runner.Async && runner.Onetime {
-			go func() {
-				err := runner.Fn(b)
+		if runner.onetime && runner.async {
+			// One-time async: fire and forget
+			bot.runnerOnceWG.Add(1)
+			go func(r Runner[T]) {
+				defer bot.runnerOnceWG.Done()
+				err := r.fn(bot)
 				if err != nil {
-					b.logger.Warnf("Runner %s failed: %s\n", runner.Name, err)
+					bot.logger.Warnf("Runner %s failed: %s\n", r.name, err)
 				}
-			}()
-		} else if !runner.Async && runner.Onetime {
+			}(runner)
+		} else if runner.onetime && !runner.async {
+			// One-time sync: block until done
 			t := time.Now()
-			err := runner.Fn(b)
+			err := runner.fn(bot)
 			if err != nil {
-				b.logger.Warnf("Runner %s failed: %s\n", runner.Name, err)
+				bot.logger.Warnf("Runner %s failed: %s\n", runner.name, err)
 			}
 			elapsed := time.Since(t)
 			if elapsed > time.Second*2 {
-				b.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.onetime && runner.async {
+			// Background loop: periodic execution with graceful shutdown
+			bot.runnerBgWG.Add(1)
+			go func(r Runner[T]) {
+				defer bot.runnerBgWG.Done()
+				ticker := time.NewTicker(r.timeout)
+				defer ticker.Stop()
 				for {
-					err := runner.Fn(b)
-					if err != nil {
-						b.logger.Warnf("Runner %s failed: %s\n", runner.Name, err)
+					select {
+					case <-ctx.Done():
+						return
+					case <-ticker.C:
+						err := r.fn(bot)
+						if err != nil {
+							bot.logger.Warnf("Runner %s failed: %s\n", r.name, err)
+						}
 					}
-					time.Sleep(runner.Timeout)
 				}
-			}()
+			}(runner)
 		}
+		// Note: !onetime && !async is already skipped above
 	}
 }

runners_test.go

@@ -0,0 +1,62 @@
+package laniakea
+
+import (
+	"context"
+	"sync/atomic"
+	"testing"
+	"time"
+
+	"git.scuroneko.dev/scuroneko/slog"
+)
+
+func TestExecRunnersRunsOnetimeSyncRunner(t *testing.T) {
+	var calls atomic.Int32
+	bot := &Bot[NoDB]{
+		logger: slog.CreateLogger(),
+		runners: []Runner[NoDB]{
+			NewRunner("sync-once", func(*Bot[NoDB]) error {
+				calls.Add(1)
+				return nil
+			}).Onetime(true).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[NoDB]{
+		logger: slog.CreateLogger(),
+		runners: []Runner[NoDB]{
+			NewRunner("background", func(*Bot[NoDB]) error {
+				if calls.Add(1) == 1 {
+					triggered <- struct{}{}
+				}
+				return nil
+			}).Timeout(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")
+	}
+}

scene.go

@@ -0,0 +1,238 @@
+package laniakea
+
+import (
+	"encoding/json"
+	"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 identifies the scene in plugin registration and session state.
+	Name string
+	// Scope controls how active scene sessions are keyed and shared.
+	Scope SceneScope
+	// Entry names the first step used by MsgContext.EnterScene.
+	Entry string
+	// PluginName stores the owning plugin name for scene resolution.
+	PluginName string
+
+	steps    map[string]SceneHandler[T]
+	commands 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]),
+		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 MsgContext.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
+}
+
+// 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]) 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
+}
+
+// SceneSession stores the active scene state for one session key.
+type SceneSession struct {
+	// Scene is the registered scene name for the active session.
+	Scene string
+	// Step is the current step name inside the active scene.
+	Step string
+	// Data stores opaque session payload bytes, typically JSON.
+	Data []byte
+}
+
+// SetData stores arbitrary opaque session data.
+func (s *SceneSession) SetData(data []byte) {
+	s.Data = data
+}
+
+// GetData returns the raw session data payload.
+func (s *SceneSession) GetData() []byte {
+	return s.Data
+}
+
+// HasData reports whether the session has a non-empty data payload.
+func (s *SceneSession) HasData() bool {
+	return len(s.Data) > 0
+}
+
+// ClearData removes any stored session data.
+func (s *SceneSession) ClearData() {
+	s.Data = nil
+}
+
+// BindData unmarshals the stored JSON payload into v.
+func (s *SceneSession) BindData(v any) error {
+	if len(s.Data) == 0 {
+		return nil
+	}
+	return json.Unmarshal(s.Data, v)
+}
+
+// SaveData marshals v as JSON and stores it in the session.
+func (s *SceneSession) SaveData(v any) error {
+	data, err := json.Marshal(v)
+	if err != nil {
+		return err
+	}
+	s.Data = data
+	return nil
+}
+
+// SessionStore persists scene sessions by key.
+type SessionStore interface {
+	Get(key string) (SceneSession, error)
+	Set(key string, session SceneSession) error
+	Delete(key string) error
+}
+
+// MemorySessionStore stores scene sessions in memory.
+type MemorySessionStore struct {
+	store map[string]SceneSession
+	mu    sync.RWMutex
+}
+
+// NewMemorySessionStore creates an empty in-memory session store.
+func NewMemorySessionStore() *MemorySessionStore {
+	return &MemorySessionStore{
+		store: make(map[string]SceneSession),
+	}
+}
+
+// Get returns the session stored under key, or the zero session when absent.
+func (s *MemorySessionStore) Get(key string) (SceneSession, error) {
+	s.mu.RLock()
+	defer s.mu.RUnlock()
+	if session, ok := s.store[key]; ok {
+		return session, nil
+	}
+	return SceneSession{}, nil
+}
+
+// Set stores session under key.
+func (s *MemorySessionStore) Set(key string, session SceneSession) error {
+	s.mu.Lock()
+	s.store[key] = session
+	s.mu.Unlock()
+	return nil
+}
+
+// Delete removes the session stored under key.
+func (s *MemorySessionStore) Delete(key string) error {
+	s.mu.Lock()
+	delete(s.store, key)
+	s.mu.Unlock()
+	return nil
+}
+
+// SceneResult describes how scene execution should proceed after a handler returns.
+type SceneResult struct {
+	Action SceneAction
+	Next   string
+}
+
+// SceneAction controls how the bot updates scene state after a handler returns.
+type SceneAction int
+
+const (
+	// SceneActionStay keeps the current scene and step active.
+	SceneActionStay SceneAction = iota
+	// SceneActionNext moves the session to another named step.
+	SceneActionNext
+	// SceneActionExit removes the current scene session.
+	SceneActionExit
+	// SceneActionPass lets normal bot routing continue after the scene handler.
+	SceneActionPass
+)
+
+// SceneScope defines how scene sessions are keyed.
+type SceneScope int
+
+const (
+	// SceneScopeUser shares a scene across all chats for one user.
+	SceneScopeUser SceneScope = iota
+	// SceneScopeChat shares a scene across all users in one chat.
+	SceneScopeChat
+	// SceneScopeUserChat isolates a scene per user-chat pair.
+	SceneScopeUserChat
+)
+
+type sceneRuntime interface {
+	findScene(name string) (*sceneMeta, bool)
+	getSession(key string) (SceneSession, error)
+	setSession(key string, session SceneSession) error
+	deleteSession(key string) error
+	buildSceneKey(scope SceneScope, ctx *MsgContext) (string, bool)
+	findSceneSession(ctx *MsgContext) (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 MsgContext with scene session state for scene handlers.
+type SceneContext struct {
+	*MsgContext
+	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,147 @@
+package laniakea
+
+import (
+	"errors"
+	"fmt"
+	"strings"
+)
+
+func (bot *Bot[T]) tryHandleScene(ctx *MsgContext) (bool, error) {
+	key, session, err := bot.findSceneSession(ctx)
+	if err != nil {
+		if errors.Is(err, ErrCantFindSession) || errors.Is(err, ErrMessageNil) {
+			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.dbContext) {
+			return false, nil
+		}
+		sceneCtx := &SceneContext{
+			MsgContext: ctx,
+			sess:       session,
+			key:        key,
+		}
+		return bot.executeScene(scene, sceneCtx)
+	}
+	return false, ErrSceneNotFound
+}
+
+func (bot *Bot[T]) executeScene(scene *Scene[T], ctx *SceneContext) (bool, error) {
+	if ctx.MsgContext == 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)
+
+		res, matched, err := scene.executeCommand(cmd, ctx, bot.dbContext)
+		if err != nil {
+			return false, err
+		}
+		if matched {
+			return bot.applySceneResult(scene, ctx, res)
+		}
+	}
+	ctx.Text = text
+	ctx.Args = nil
+	ctx.Prefix = ""
+	if ctx.sess.Step != "" {
+		res, matched, err := scene.executeStep(ctx.sess.Step, ctx, bot.dbContext)
+		if err != nil {
+			return false, err
+		}
+		if matched {
+			return bot.applySceneResult(scene, ctx, res)
+		}
+	}
+
+	res, matched, err := scene.executeMessage(ctx, bot.dbContext)
+	if err != nil {
+		return false, err
+	}
+	if matched {
+		return bot.applySceneResult(scene, ctx, res)
+	}
+
+	return false, nil
+}
+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 *MsgContext) (string, bool) {
+	if ctx == nil {
+		return "", false
+	}
+
+	switch scope {
+	case SceneScopeUserChat:
+		if ctx.Msg == nil || ctx.Msg.Chat == nil || ctx.FromID == 0 {
+			return "", false
+		}
+		return fmt.Sprintf("user_id:%d:chat_id:%d", ctx.FromID, ctx.Msg.Chat.ID), true
+	case SceneScopeChat:
+		if ctx.Msg == nil || ctx.Msg.Chat == nil {
+			return "", false
+		}
+		return fmt.Sprintf("chat_id:%d", ctx.Msg.Chat.ID), true
+	case SceneScopeUser:
+		if ctx.FromID == 0 {
+			return "", false
+		}
+		return fmt.Sprintf("user_id:%d", ctx.FromID), true
+	default:
+		return "", false
+	}
+}

scene_test.go

@@ -0,0 +1,468 @@
+package laniakea
+
+import (
+	"context"
+	"errors"
+	"testing"
+
+	"git.scuroneko.dev/scuroneko/laniakea/tgapi"
+	"git.scuroneko.dev/scuroneko/slog"
+)
+
+type failingSessionStore struct {
+	getErr    error
+	setErr    error
+	deleteErr error
+}
+
+func (s failingSessionStore) Get(key string) (SceneSession, error) {
+	return SceneSession{}, s.getErr
+}
+
+func (s failingSessionStore) Set(key string, session SceneSession) error {
+	return s.setErr
+}
+
+func (s failingSessionStore) Delete(key string) error {
+	return s.deleteErr
+}
+
+func TestPluginAddSceneRegistersScene(t *testing.T) {
+	plugin := NewPlugin[NoDB]("wizard")
+	scene := NewScene[NoDB]("signup")
+
+	plugin.AddScene(scene)
+
+	if got, ok := plugin.scenes["signup"]; !ok || got != scene {
+		t.Fatalf("scene was not registered in plugin: ok=%v got=%p want=%p", ok, got, scene)
+	}
+	if scene.PluginName != "wizard" {
+		t.Fatalf("unexpected plugin name on scene: got %q want %q", scene.PluginName, "wizard")
+	}
+}
+
+func TestBotAddPluginsPreservesScenesAndHandlesThem(t *testing.T) {
+	called := false
+
+	plugin := NewPlugin[NoDB]("wizard")
+	plugin.NewScene("signup").
+		SetEntry("start").
+		OnStep("start", func(ctx *SceneContext, db NoDB) (SceneResult, error) {
+			called = true
+			if ctx.Text != "hello there" {
+				t.Fatalf("unexpected scene text: got %q want %q", ctx.Text, "hello there")
+			}
+			return ctx.Exit(), nil
+		})
+
+	bot := &Bot[NoDB]{
+		logger:             slog.CreateLogger(),
+		prefixes:           []string{"/"},
+		sessionStore:       NewMemorySessionStore(),
+		sceneScopePriority: []SceneScope{SceneScopeUserChat, SceneScopeChat, SceneScopeUser},
+	}
+	bot.AddPlugins(plugin)
+
+	sceneMeta, ok := bot.findScene("signup")
+	if !ok {
+		t.Fatal("expected scene metadata to be available after plugin registration")
+	}
+	if sceneMeta.Entry != "start" {
+		t.Fatalf("unexpected scene entry: got %q want %q", sceneMeta.Entry, "start")
+	}
+
+	enterCtx := &MsgContext{
+		Msg:          &tgapi.Message{Chat: &tgapi.Chat{ID: 100, Type: string(tgapi.ChatTypePrivate)}},
+		FromID:       42,
+		sceneRuntime: bot,
+	}
+	if err := enterCtx.EnterScene("signup"); err != nil {
+		t.Fatalf("EnterScene returned error: %v", err)
+	}
+
+	bot.handle(context.Background(), &tgapi.Update{
+		UpdateID: 1,
+		Type:     tgapi.UpdateTypeMessage,
+		Message: &tgapi.Message{
+			MessageID: 7,
+			Text:      "hello there",
+			Chat:      &tgapi.Chat{ID: 100, Type: string(tgapi.ChatTypePrivate)},
+			From:      &tgapi.User{ID: 42},
+		},
+	})
+
+	if !called {
+		t.Fatal("expected scene step handler to be called")
+	}
+
+	lookupCtx := &MsgContext{
+		Msg:    &tgapi.Message{Chat: &tgapi.Chat{ID: 100, Type: string(tgapi.ChatTypePrivate)}},
+		FromID: 42,
+	}
+	if _, session, err := bot.findSceneSession(lookupCtx); err == nil && session.Scene != "" {
+		t.Fatalf("expected scene session to be removed after exit, got %#v", session)
+	}
+}
+
+func TestBuildSceneKeyRejectsMissingContextFields(t *testing.T) {
+	tests := []struct {
+		name  string
+		scope SceneScope
+		ctx   *MsgContext
+	}{
+		{
+			name:  "nil context",
+			scope: SceneScopeUserChat,
+			ctx:   nil,
+		},
+		{
+			name:  "missing message for chat scope",
+			scope: SceneScopeChat,
+			ctx:   &MsgContext{},
+		},
+		{
+			name:  "missing from id for user scope",
+			scope: SceneScopeUser,
+			ctx:   &MsgContext{},
+		},
+		{
+			name:  "missing from id for user chat scope",
+			scope: SceneScopeUserChat,
+			ctx: &MsgContext{
+				Msg: &tgapi.Message{Chat: &tgapi.Chat{ID: 100, Type: string(tgapi.ChatTypePrivate)}},
+			},
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			if key, ok := buildSceneKey(tt.scope, tt.ctx); ok || key != "" {
+				t.Fatalf("expected invalid scene key, got key=%q ok=%v", key, ok)
+			}
+		})
+	}
+}
+
+func TestEnterSceneRejectsMissingEntryConfiguration(t *testing.T) {
+	t.Run("empty entry", func(t *testing.T) {
+		plugin := NewPlugin[NoDB]("wizard")
+		plugin.NewScene("signup")
+
+		bot := &Bot[NoDB]{
+			logger:             slog.CreateLogger(),
+			sessionStore:       NewMemorySessionStore(),
+			sceneScopePriority: []SceneScope{SceneScopeUserChat, SceneScopeChat, SceneScopeUser},
+		}
+		bot.AddPlugins(plugin)
+
+		ctx := &MsgContext{
+			Msg:          &tgapi.Message{Chat: &tgapi.Chat{ID: 100, Type: string(tgapi.ChatTypePrivate)}},
+			FromID:       42,
+			sceneRuntime: bot,
+		}
+
+		err := ctx.EnterScene("signup")
+		if !errors.Is(err, ErrSceneEntryNotSet) {
+			t.Fatalf("expected ErrSceneEntryNotSet, got %v", err)
+		}
+	})
+
+	t.Run("missing entry step", func(t *testing.T) {
+		plugin := NewPlugin[NoDB]("wizard")
+		plugin.NewScene("signup").SetEntry("start")
+
+		bot := &Bot[NoDB]{
+			logger:             slog.CreateLogger(),
+			sessionStore:       NewMemorySessionStore(),
+			sceneScopePriority: []SceneScope{SceneScopeUserChat, SceneScopeChat, SceneScopeUser},
+		}
+		bot.AddPlugins(plugin)
+
+		ctx := &MsgContext{
+			Msg:          &tgapi.Message{Chat: &tgapi.Chat{ID: 100, Type: string(tgapi.ChatTypePrivate)}},
+			FromID:       42,
+			sceneRuntime: bot,
+		}
+
+		err := ctx.EnterScene("signup")
+		if !errors.Is(err, ErrSceneStepNotFound) {
+			t.Fatalf("expected ErrSceneStepNotFound, got %v", err)
+		}
+	})
+}
+
+func TestSceneContextMethodsRequireRuntime(t *testing.T) {
+	ctx := &MsgContext{}
+
+	if err := ctx.EnterScene("signup"); !errors.Is(err, ErrSceneRuntimeNil) {
+		t.Fatalf("expected ErrSceneRuntimeNil from EnterScene, got %v", err)
+	}
+	if err := ctx.EnterSceneStep("signup", "start"); !errors.Is(err, ErrSceneRuntimeNil) {
+		t.Fatalf("expected ErrSceneRuntimeNil from EnterSceneStep, got %v", err)
+	}
+	if err := ctx.ExitScene(); !errors.Is(err, ErrSceneRuntimeNil) {
+		t.Fatalf("expected ErrSceneRuntimeNil from ExitScene, got %v", err)
+	}
+}
+
+func TestSceneCommandHandlerRunsBeforeStep(t *testing.T) {
+	sceneCommandCalled := false
+	stepCalled := false
+
+	plugin := NewPlugin[NoDB]("wizard")
+	plugin.NewScene("signup").
+		SetEntry("start").
+		OnStep("start", func(ctx *SceneContext, db NoDB) (SceneResult, error) {
+			stepCalled = true
+			return ctx.Stay(), nil
+		}).
+		OnCommand("cancel", func(ctx *SceneContext, db NoDB) (SceneResult, error) {
+			sceneCommandCalled = true
+			if ctx.Prefix != "/" {
+				t.Fatalf("unexpected prefix: got %q want /", ctx.Prefix)
+			}
+			if ctx.Text != "right now" {
+				t.Fatalf("unexpected scene command text: got %q want %q", ctx.Text, "right now")
+			}
+			if len(ctx.Args) != 2 || ctx.Args[0] != "right" || ctx.Args[1] != "now" {
+				t.Fatalf("unexpected scene command args: %#v", ctx.Args)
+			}
+			return ctx.Exit(), nil
+		})
+
+	bot := &Bot[NoDB]{
+		logger:             slog.CreateLogger(),
+		prefixes:           []string{"/"},
+		sessionStore:       NewMemorySessionStore(),
+		sceneScopePriority: []SceneScope{SceneScopeUserChat, SceneScopeChat, SceneScopeUser},
+	}
+	bot.AddPlugins(plugin)
+
+	enterCtx := &MsgContext{
+		Msg:          &tgapi.Message{Chat: &tgapi.Chat{ID: 100, Type: string(tgapi.ChatTypePrivate)}},
+		FromID:       42,
+		sceneRuntime: bot,
+	}
+	if err := enterCtx.EnterScene("signup"); err != nil {
+		t.Fatalf("EnterScene returned error: %v", err)
+	}
+
+	bot.handle(context.Background(), &tgapi.Update{
+		UpdateID: 2,
+		Type:     tgapi.UpdateTypeMessage,
+		Message: &tgapi.Message{
+			MessageID: 8,
+			Text:      "/cancel right now",
+			Chat:      &tgapi.Chat{ID: 100, Type: string(tgapi.ChatTypePrivate)},
+			From:      &tgapi.User{ID: 42},
+		},
+	})
+
+	if !sceneCommandCalled {
+		t.Fatal("expected scene command handler to be called")
+	}
+	if stepCalled {
+		t.Fatal("expected scene command to short-circuit the scene step")
+	}
+}
+
+func TestScenePassDoesNotPersistSessionData(t *testing.T) {
+	commandCalled := false
+
+	plugin := NewPlugin[NoDB]("wizard")
+	plugin.NewCommand(func(ctx *MsgContext, db NoDB) error {
+		commandCalled = true
+		return nil
+	}, "ping")
+	plugin.NewScene("signup").
+		SetEntry("start").
+		OnStep("start", func(ctx *SceneContext, db NoDB) (SceneResult, error) {
+			if err := ctx.SaveData(struct {
+				Value string `json:"value"`
+			}{Value: "changed"}); err != nil {
+				t.Fatalf("SaveData returned error: %v", err)
+			}
+			return ctx.Pass(), nil
+		})
+
+	bot := &Bot[NoDB]{
+		logger:             slog.CreateLogger(),
+		prefixes:           []string{"/"},
+		sessionStore:       NewMemorySessionStore(),
+		sceneScopePriority: []SceneScope{SceneScopeUserChat, SceneScopeChat, SceneScopeUser},
+	}
+	bot.AddPlugins(plugin)
+
+	enterCtx := &MsgContext{
+		Msg:          &tgapi.Message{Chat: &tgapi.Chat{ID: 100, Type: string(tgapi.ChatTypePrivate)}},
+		FromID:       42,
+		sceneRuntime: bot,
+	}
+	if err := enterCtx.EnterScene("signup"); err != nil {
+		t.Fatalf("EnterScene returned error: %v", err)
+	}
+
+	key, ok := buildSceneKey(SceneScopeUserChat, &MsgContext{
+		Msg:    &tgapi.Message{Chat: &tgapi.Chat{ID: 100, Type: string(tgapi.ChatTypePrivate)}},
+		FromID: 42,
+	})
+	if !ok {
+		t.Fatal("expected scene key to be built")
+	}
+
+	before, err := bot.sessionStore.Get(key)
+	if err != nil {
+		t.Fatalf("Get before handle returned error: %v", err)
+	}
+	if before.HasData() {
+		t.Fatalf("expected empty session data before handle, got %#v", before)
+	}
+
+	bot.handle(context.Background(), &tgapi.Update{
+		UpdateID: 3,
+		Type:     tgapi.UpdateTypeMessage,
+		Message: &tgapi.Message{
+			MessageID: 9,
+			Text:      "/ping",
+			Chat:      &tgapi.Chat{ID: 100, Type: string(tgapi.ChatTypePrivate)},
+			From:      &tgapi.User{ID: 42},
+		},
+	})
+
+	if !commandCalled {
+		t.Fatal("expected normal command routing to continue after SceneActionPass")
+	}
+
+	after, err := bot.sessionStore.Get(key)
+	if err != nil {
+		t.Fatalf("Get after handle returned error: %v", err)
+	}
+	if after.Scene != "signup" || after.Step != "start" {
+		t.Fatalf("unexpected session after pass: %#v", after)
+	}
+	if after.HasData() {
+		t.Fatalf("expected SceneActionPass to leave session data unchanged, got %#v", after)
+	}
+}
+
+func TestSceneMessageFallbackRunsWhenNoCommandOrStepMatch(t *testing.T) {
+	fallbackCalled := false
+
+	plugin := NewPlugin[NoDB]("wizard")
+	plugin.NewScene("signup").
+		SetEntry("start").
+		OnStep("start", func(ctx *SceneContext, db NoDB) (SceneResult, error) {
+			return ctx.Stay(), nil
+		}).
+		OnMessage(func(ctx *SceneContext, db NoDB) (SceneResult, error) {
+			fallbackCalled = true
+			if ctx.Text != "hello fallback" {
+				t.Fatalf("unexpected fallback text: got %q want %q", ctx.Text, "hello fallback")
+			}
+			return ctx.Exit(), nil
+		})
+
+	bot := &Bot[NoDB]{
+		logger:             slog.CreateLogger(),
+		prefixes:           []string{"/"},
+		sessionStore:       NewMemorySessionStore(),
+		sceneScopePriority: []SceneScope{SceneScopeUserChat, SceneScopeChat, SceneScopeUser},
+	}
+	bot.AddPlugins(plugin)
+
+	enterCtx := &MsgContext{
+		Msg:          &tgapi.Message{Chat: &tgapi.Chat{ID: 100, Type: string(tgapi.ChatTypePrivate)}},
+		FromID:       42,
+		sceneRuntime: bot,
+	}
+	if err := enterCtx.EnterScene("signup"); err != nil {
+		t.Fatalf("EnterScene returned error: %v", err)
+	}
+
+	key, ok := buildSceneKey(SceneScopeUserChat, &MsgContext{
+		Msg:    &tgapi.Message{Chat: &tgapi.Chat{ID: 100, Type: string(tgapi.ChatTypePrivate)}},
+		FromID: 42,
+	})
+	if !ok {
+		t.Fatal("expected scene key to be built")
+	}
+	if err := bot.sessionStore.Set(key, SceneSession{Scene: "signup", Step: "unknown"}); err != nil {
+		t.Fatalf("Set returned error: %v", err)
+	}
+
+	bot.handle(context.Background(), &tgapi.Update{
+		UpdateID: 4,
+		Type:     tgapi.UpdateTypeMessage,
+		Message: &tgapi.Message{
+			MessageID: 10,
+			Text:      "hello fallback",
+			Chat:      &tgapi.Chat{ID: 100, Type: string(tgapi.ChatTypePrivate)},
+			From:      &tgapi.User{ID: 42},
+		},
+	})
+
+	if !fallbackCalled {
+		t.Fatal("expected scene fallback handler to be called")
+	}
+}
+
+func TestFindSceneSessionSupportsUserScopeWithoutMessage(t *testing.T) {
+	bot := &Bot[NoDB]{
+		logger:             slog.CreateLogger(),
+		sessionStore:       NewMemorySessionStore(),
+		sceneScopePriority: []SceneScope{SceneScopeUser, SceneScopeChat, SceneScopeUserChat},
+	}
+
+	if err := bot.sessionStore.Set("user_id:42", SceneSession{Scene: "signup", Step: "start"}); err != nil {
+		t.Fatalf("Set returned error: %v", err)
+	}
+
+	key, session, err := bot.findSceneSession(&MsgContext{FromID: 42})
+	if err != nil {
+		t.Fatalf("findSceneSession returned error: %v", err)
+	}
+	if key != "user_id:42" {
+		t.Fatalf("unexpected session key: got %q want %q", key, "user_id:42")
+	}
+	if session.Scene != "signup" || session.Step != "start" {
+		t.Fatalf("unexpected session: %#v", session)
+	}
+}
+
+func TestSceneStoreErrorsPropagate(t *testing.T) {
+	getErr := errors.New("get failed")
+	setErr := errors.New("set failed")
+
+	t.Run("find scene session get error", func(t *testing.T) {
+		bot := &Bot[NoDB]{
+			logger:             slog.CreateLogger(),
+			sessionStore:       failingSessionStore{getErr: getErr},
+			sceneScopePriority: []SceneScope{SceneScopeUser},
+		}
+
+		_, _, err := bot.findSceneSession(&MsgContext{FromID: 42})
+		if !errors.Is(err, getErr) {
+			t.Fatalf("expected getErr, got %v", err)
+		}
+	})
+
+	t.Run("apply scene result set error", func(t *testing.T) {
+		scene := NewScene[NoDB]("signup").OnStep("start", func(ctx *SceneContext, db NoDB) (SceneResult, error) {
+			return ctx.Stay(), nil
+		})
+		bot := &Bot[NoDB]{
+			logger:             slog.CreateLogger(),
+			sessionStore:       failingSessionStore{setErr: setErr},
+			sceneScopePriority: []SceneScope{SceneScopeUserChat, SceneScopeChat, SceneScopeUser},
+		}
+
+		_, err := bot.applySceneResult(scene, &SceneContext{
+			MsgContext: &MsgContext{},
+			sess:       SceneSession{Scene: "signup", Step: "start"},
+			key:        "user_id:42:chat_id:100",
+		}, SceneResult{Action: SceneActionStay})
+		if !errors.Is(err, setErr) {
+			t.Fatalf("expected setErr, got %v", err)
+		}
+	})
+}

split.go

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

tgapi/api.go

@@ -0,0 +1,308 @@
+package tgapi
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"fmt"
+	"io"
+	"net/http"
+	"time"
+
+	"git.scuroneko.dev/scuroneko/laniakea/utils"
+	"git.scuroneko.dev/scuroneko/slog"
+)
+
+// APIOpts holds configuration options for initializing the Telegram API client.
+// Use the provided setter methods to build options — do not construct directly.
+type APIOpts struct {
+	token         string
+	client        *http.Client
+	useTestServer bool
+	apiUrl        string
+
+	limiter           *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",
+	}
+}
+
+// SetHTTPClient sets a custom HTTP client. Use this for timeouts, proxies, or custom transport.
+// If not set, a default client with 45s timeout is used.
+func (opts *APIOpts) SetHTTPClient(client *http.Client) *APIOpts {
+	if client != nil {
+		opts.client = client
+	}
+	return opts
+}
+
+// UseTestServer enables use of Telegram's test server (https://api.test.telegram.org).
+// Only for development/testing.
+func (opts *APIOpts) UseTestServer(use bool) *APIOpts {
+	opts.useTestServer = use
+	return opts
+}
+
+// SetAPIUrl overrides the default Telegram API URL.
+// Useful for self-hosted bots or proxies.
+func (opts *APIOpts) SetAPIUrl(apiUrl string) *APIOpts {
+	if apiUrl != "" {
+		opts.apiUrl = apiUrl
+	}
+	return opts
+}
+
+// SetLimiter sets a rate limiter to enforce Telegram's API limits.
+// Recommended: use utils.NewRateLimiter() for correct per-chat and global throttling.
+func (opts *APIOpts) SetLimiter(limiter *utils.RateLimiter) *APIOpts {
+	opts.limiter = limiter
+	return opts
+}
+
+// SetLimiterDrop enables "drop mode" for rate limiting.
+// If true, requests exceeding limits return ErrDropOverflow immediately.
+// If false, requests block until capacity is available.
+func (opts *APIOpts) SetLimiterDrop(b bool) *APIOpts {
+	opts.dropOverflowLimit = b
+	return opts
+}
+
+// API is the main Telegram Bot API client 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
+	useTestServer bool
+	apiUrl        string
+
+	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 := utils.CreateLogger("API", utils.GetLoggerLevel())
+
+	client := opts.client
+	if client == nil {
+		client = &http.Client{Timeout: time.Second * 45}
+	}
+
+	pool := newWorkerPool(16, 256)
+	pool.start()
+
+	return &API{
+		token:             opts.token,
+		client:            client,
+		logger:            l,
+		useTestServer:     opts.useTestServer,
+		apiUrl:            opts.apiUrl,
+		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() *slog.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"`
+}
+
+// ApiResponse is the standard Telegram Bot API response structure.
+// Generic over Result type R.
+type ApiResponse[R any] struct {
+	Ok          bool                `json:"ok"`
+	Description string              `json:"description,omitempty"`
+	Result      R                   `json:"result,omitempty"`
+	ErrorCode   int                 `json:"error_code,omitempty"`
+	Parameters  *ResponseParameters `json:"parameters,omitempty"`
+}
+
+// TelegramRequest is 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, params, 0}
+}
+
+// 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
+	reqData, err := json.Marshal(r.params)
+	if err != nil {
+		return zero, fmt.Errorf("failed to marshal request: %w", err)
+	}
+
+	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, nil)
+	if err != nil {
+		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))
+
+	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))
+
+		api.logger.Debugln("REQ", url, string(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", r.method, string(respData))
+
+		response, err := parseBody[R](respData)
+		if err != nil {
+			return zero, fmt.Errorf("failed to parse response: %w", err)
+		}
+
+		if !response.Ok {
+			// Handle rate limiting (429)
+			if response.ErrorCode == 429 && response.Parameters != nil && response.Parameters.RetryAfter != nil {
+				after := *response.Parameters.RetryAfter
+				api.logger.Warnf("Rate limited by Telegram, retry after %d seconds (chat: %d)", after, r.chatId)
+
+				// Apply cooldown to global or chat-specific limiter
+				if api.Limiter != nil {
+					if r.chatId > 0 {
+						api.Limiter.SetChatLock(r.chatId, after)
+					} else {
+						api.Limiter.SetGlobalLock(after)
+					}
+				}
+
+				// Wait and retry
+				select {
+				case <-ctx.Done():
+					return zero, ctx.Err()
+				case <-time.After(time.Duration(after) * time.Second):
+					continue // retry request
+				}
+			}
+
+			// Other API errors
+			return zero, fmt.Errorf("[%d] %s", response.ErrorCode, response.Description)
+		}
+
+		return response.Result, nil
+	}
+}
+
+// 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)
+}
+
+// Internal helper that reads and caps a Telegram response body.
+func readBody(body io.ReadCloser) ([]byte, error) {
+	reader := io.LimitReader(body, 10<<20) // 10 MB
+	return io.ReadAll(reader)
+}
+
+// Internal helper that parses a typed Telegram API response body.
+func parseBody[R any](data []byte) (ApiResponse[R], error) {
+	var resp ApiResponse[R]
+	err := json.Unmarshal(data, &resp)
+	if err != nil {
+		return resp, fmt.Errorf("failed to unmarshal JSON: %w", err)
+	}
+	return resp, nil
+}

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

@@ -0,0 +1,362 @@
+package tgapi
+
+import "context"
+
+// SendPhotoP holds parameters for the sendPhoto method.
+// See https://core.telegram.org/bots/api#sendphoto
+type SendPhotoP 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"`
+
+	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"`
+	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"`
+
+	SuggestedPostParameters *SuggestedPostParameters `json:"suggested_post_parameters,omitempty"`
+	ReplyParameters         *ReplyParameters         `json:"reply_parameters,omitempty"`
+	ReplyMarkup             *ReplyMarkup             `json:"reply_markup,omitempty"`
+}
+
+// SendPhoto sends a photo.
+// See https://core.telegram.org/bots/api#sendphoto
+func (api *API) SendPhoto(params SendPhotoP) (Message, error) {
+	req := NewRequestWithChatID[Message]("sendPhoto", params, params.ChatID)
+	return req.Do(api)
+}
+
+// SendPhotoWithContext is the context-aware variant of SendPhoto.
+// It executes the same request but uses ctx for cancellation and deadlines.
+// See https://core.telegram.org/bots/api#sendphoto
+func (api *API) SendPhotoWithContext(ctx context.Context, params SendPhotoP) (Message, error) {
+	req := NewRequestWithChatID[Message]("sendPhoto", params, params.ChatID)
+	return req.DoWithContext(ctx, api)
+}
+
+// SendAudioP holds parameters for the sendAudio method.
+// See https://core.telegram.org/bots/api#sendaudio
+type SendAudioP 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"`
+
+	Audio           string          `json:"audio"`
+	Caption         string          `json:"caption,omitempty"`
+	ParseMode       ParseMode       `json:"parse_mode,omitempty"`
+	CaptionEntities []MessageEntity `json:"caption_entities,omitempty"`
+	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"`
+	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"`
+}
+
+// SendAudio sends an audio file.
+// See https://core.telegram.org/bots/api#sendaudio
+func (api *API) SendAudio(params SendAudioP) (Message, error) {
+	req := NewRequestWithChatID[Message]("sendAudio", params, params.ChatID)
+	return req.Do(api)
+}
+
+// SendAudioWithContext is the context-aware variant of SendAudio.
+// It executes the same request but uses ctx for cancellation and deadlines.
+// See https://core.telegram.org/bots/api#sendaudio
+func (api *API) SendAudioWithContext(ctx context.Context, params SendAudioP) (Message, error) {
+	req := NewRequestWithChatID[Message]("sendAudio", params, params.ChatID)
+	return req.DoWithContext(ctx, api)
+}
+
+// SendDocumentP holds parameters for the sendDocument method.
+// See https://core.telegram.org/bots/api#senddocument
+type SendDocumentP 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"`
+
+	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"`
+	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"`
+}
+
+// SendDocument sends a document.
+// See https://core.telegram.org/bots/api#senddocument
+func (api *API) SendDocument(params SendDocumentP) (Message, error) {
+	req := NewRequestWithChatID[Message]("sendDocument", params, params.ChatID)
+	return req.Do(api)
+}
+
+// SendDocumentWithContext is the context-aware variant of SendDocument.
+// It executes the same request but uses ctx for cancellation and deadlines.
+// See https://core.telegram.org/bots/api#senddocument
+func (api *API) SendDocumentWithContext(ctx context.Context, params SendDocumentP) (Message, error) {
+	req := NewRequestWithChatID[Message]("sendDocument", params, params.ChatID)
+	return req.DoWithContext(ctx, api)
+}
+
+// SendVideoP holds parameters for the sendVideo method.
+// See https://core.telegram.org/bots/api#sendvideo
+type SendVideoP 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"`
+
+	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"`
+	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"`
+	SupportsStreaming     bool   `json:"supports_streaming,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"`
+}
+
+// SendVideo sends a video.
+// See https://core.telegram.org/bots/api#sendvideo
+func (api *API) SendVideo(params SendVideoP) (Message, error) {
+	req := NewRequestWithChatID[Message]("sendVideo", params, params.ChatID)
+	return req.Do(api)
+}
+
+// SendVideoWithContext is the context-aware variant of SendVideo.
+// It executes the same request but uses ctx for cancellation and deadlines.
+// See https://core.telegram.org/bots/api#sendvideo
+func (api *API) SendVideoWithContext(ctx context.Context, params SendVideoP) (Message, error) {
+	req := NewRequestWithChatID[Message]("sendVideo", params, params.ChatID)
+	return req.DoWithContext(ctx, api)
+}
+
+// SendAnimationP holds parameters for the sendAnimation method.
+// See https://core.telegram.org/bots/api#sendanimation
+type SendAnimationP 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"`
+
+	Animation string `json:"animation"`
+	Thumbnail string `json:"thumbnail,omitempty"`
+	Duration  int    `json:"duration,omitempty"`
+	Width     int    `json:"width,omitempty"`
+	Height    int    `json:"height,omitempty"`
+
+	Caption               string          `json:"caption,omitempty"`
+	ParseMode             ParseMode       `json:"parse_mode,omitempty"`
+	CaptionEntities       []MessageEntity `json:"caption_entities,omitempty"`
+	ShowCaptionAboveMedia bool            `json:"show_caption_above_media,omitempty"`
+	HasSpoiler            bool            `json:"has_spoiler,omitempty"`
+	DisableNotification   bool            `json:"disable_notification,omitempty"`
+	ProtectContent        bool            `json:"protect_content,omitempty"`
+	AllowPaidBroadcast    bool            `json:"allow_paid_broadcast,omitempty"`
+	MessageEffectID       string          `json:"message_effect_id,omitempty"`
+
+	SuggestedPostParameters *SuggestedPostParameters `json:"suggested_post_parameters,omitempty"`
+	ReplyParameters         *ReplyParameters         `json:"reply_parameters,omitempty"`
+	ReplyMarkup             *ReplyMarkup             `json:"reply_markup,omitempty"`
+}
+
+// SendAnimation sends an animation file (GIF or H.264/MPEG-4 AVC video without sound).
+// See https://core.telegram.org/bots/api#sendanimation
+func (api *API) SendAnimation(params SendAnimationP) (Message, error) {
+	req := NewRequestWithChatID[Message]("sendAnimation", params, params.ChatID)
+	return req.Do(api)
+}
+
+// SendAnimationWithContext is the context-aware variant of SendAnimation.
+// It executes the same request but uses ctx for cancellation and deadlines.
+// See https://core.telegram.org/bots/api#sendanimation
+func (api *API) SendAnimationWithContext(ctx context.Context, params SendAnimationP) (Message, error) {
+	req := NewRequestWithChatID[Message]("sendAnimation", params, params.ChatID)
+	return req.DoWithContext(ctx, api)
+}
+
+// SendVoiceP holds parameters for the sendVoice method.
+// See https://core.telegram.org/bots/api#sendvoice
+type SendVoiceP 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"`
+
+	Voice               string          `json:"voice"`
+	Caption             string          `json:"caption,omitempty"`
+	ParseMode           ParseMode       `json:"parse_mode,omitempty"`
+	CaptionEntities     []MessageEntity `json:"caption_entities,omitempty"`
+	Duration            int             `json:"duration,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"`
+}
+
+// SendVoice sends a voice note.
+// See https://core.telegram.org/bots/api#sendvoice
+func (api *API) SendVoice(params SendVoiceP) (Message, error) {
+	req := NewRequestWithChatID[Message]("sendVoice", params, params.ChatID)
+	return req.Do(api)
+}
+
+// SendVoiceWithContext is the context-aware variant of SendVoice.
+// It executes the same request but uses ctx for cancellation and deadlines.
+// See https://core.telegram.org/bots/api#sendvoice
+func (api *API) SendVoiceWithContext(ctx context.Context, params SendVoiceP) (Message, error) {
+	req := NewRequestWithChatID[Message]("sendVoice", params, params.ChatID)
+	return req.DoWithContext(ctx, api)
+}
+
+// SendVideoNoteP holds parameters for the sendVideoNote method.
+// See https://core.telegram.org/bots/api#sendvideonote
+type SendVideoNoteP 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"`
+
+	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"`
+	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"`
+}
+
+// SendVideoNote sends a video note (rounded video message).
+// See https://core.telegram.org/bots/api#sendvideonote
+func (api *API) SendVideoNote(params SendVideoNoteP) (Message, error) {
+	req := NewRequestWithChatID[Message]("sendVideoNote", params, params.ChatID)
+	return req.Do(api)
+}
+
+// SendVideoNoteWithContext is the context-aware variant of SendVideoNote.
+// It executes the same request but uses ctx for cancellation and deadlines.
+// See https://core.telegram.org/bots/api#sendvideonote
+func (api *API) SendVideoNoteWithContext(ctx context.Context, params SendVideoNoteP) (Message, error) {
+	req := NewRequestWithChatID[Message]("sendVideoNote", params, params.ChatID)
+	return req.DoWithContext(ctx, api)
+}
+
+// SendPaidMediaP holds parameters for the sendPaidMedia method.
+// See https://core.telegram.org/bots/api#sendpaidmedia
+type SendPaidMediaP 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"`
+	StarCount             int    `json:"star_count,omitempty"`
+
+	Media                 []InputPaidMedia `json:"media"`
+	Payload               string           `json:"payload,omitempty"`
+	Caption               string           `json:"caption,omitempty"`
+	ParseMode             ParseMode        `json:"parse_mode,omitempty"`
+	CaptionEntities       []MessageEntity  `json:"caption_entities,omitempty"`
+	ShowCaptionAboveMedia bool             `json:"show_caption_above_media,omitempty"`
+	DisableNotification   bool             `json:"disable_notification,omitempty"`
+	ProtectContent        bool             `json:"protect_content,omitempty"`
+	AllowPaidBroadcast    bool             `json:"allow_paid_broadcast,omitempty"`
+
+	SuggestedPostParameters *SuggestedPostParameters `json:"suggested_post_parameters,omitempty"`
+	ReplyParameters         *ReplyParameters         `json:"reply_parameters,omitempty"`
+	ReplyMarkup             *ReplyMarkup             `json:"reply_markup,omitempty"`
+}
+
+// SendPaidMedia sends paid media.
+// See https://core.telegram.org/bots/api#sendpaidmedia
+func (api *API) SendPaidMedia(params SendPaidMediaP) (Message, error) {
+	req := NewRequestWithChatID[Message]("sendPaidMedia", params, params.ChatID)
+	return req.Do(api)
+}
+
+// SendPaidMediaWithContext is the context-aware variant of SendPaidMedia.
+// It executes the same request but uses ctx for cancellation and deadlines.
+// See https://core.telegram.org/bots/api#sendpaidmedia
+func (api *API) SendPaidMediaWithContext(ctx context.Context, params SendPaidMediaP) (Message, error) {
+	req := NewRequestWithChatID[Message]("sendPaidMedia", params, params.ChatID)
+	return req.DoWithContext(ctx, api)
+}
+
+// SendMediaGroupP holds parameters for the sendMediaGroup method.
+// See https://core.telegram.org/bots/api#sendmediagroup
+type SendMediaGroupP 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"`
+
+	Media               []InputMedia     `json:"media"`
+	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"`
+}
+
+// SendMediaGroup sends a group of photos, videos, documents or audios as an album.
+// See https://core.telegram.org/bots/api#sendmediagroup
+func (api *API) SendMediaGroup(params SendMediaGroupP) ([]Message, error) {
+	req := NewRequestWithChatID[[]Message]("sendMediaGroup", params, params.ChatID)
+	return req.Do(api)
+}
+
+// SendMediaGroupWithContext is the context-aware variant of SendMediaGroup.
+// It executes the same request but uses ctx for cancellation and deadlines.
+// See https://core.telegram.org/bots/api#sendmediagroup
+func (api *API) SendMediaGroupWithContext(ctx context.Context, params SendMediaGroupP) ([]Message, error) {
+	req := NewRequestWithChatID[[]Message]("sendMediaGroup", params, params.ChatID)
+	return req.DoWithContext(ctx, api)
+}

tgapi/attachments_types.go

@@ -0,0 +1,74 @@
+package tgapi
+
+// 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"
+)
+
+// InputMedia represents the content of a media message to be sent.
+// It is a union type described in https://core.telegram.org/bots/api#inputmedia.
+type InputMedia struct {
+	Type  InputMediaType `json:"type"`
+	Media string         `json:"media"`
+
+	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"`
+
+	Cover             *string `json:"cover"`
+	StartTimestamp    *int    `json:"start_timestamp"`
+	Width             *int    `json:"width,omitempty"`
+	Height            *int    `json:"height,omitempty"`
+	Duration          *int    `json:"duration,omitempty"`
+	SupportsStreaming *bool   `json:"supports_streaming,omitempty"`
+
+	Performer *string `json:"performer,omitempty"`
+	Title     *string `json:"title,omitempty"`
+}
+
+// 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"
+)
+
+// InputPaidMedia describes the paid media to be sent.
+// See https://core.telegram.org/bots/api#inputpaidmedia
+type InputPaidMedia struct {
+	Type  InputPaidMediaType `json:"type"`
+	Media string             `json:"media"`
+
+	Cover             *string `json:"cover,omitempty"`
+	StartTimestamp    *int64  `json:"start_timestamp,omitempty"`
+	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.
+// 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     int64  `json:"file_size,omitempty"`
+}

tgapi/bot_methods.go

@@ -0,0 +1,400 @@
+package tgapi
+
+import "context"
+
+// SetMyCommandsP holds parameters for the setMyCommands method.
+// See https://core.telegram.org/bots/api#setmycommands
+type SetMyCommandsP struct {
+	Commands []BotCommand     `json:"commands"`
+	Scope    *BotCommandScope `json:"scope,omitempty"`
+	Language string           `json:"language_code,omitempty"`
+}
+
+// SetMyCommands changes the list of the bot's commands.
+// Returns true on success.
+// See https://core.telegram.org/bots/api#setmycommands
+func (api *API) SetMyCommands(params SetMyCommandsP) (bool, error) {
+	req := NewRequest[bool]("setMyCommands", params)
+	return req.Do(api)
+}
+
+// SetMyCommandsWithContext is the context-aware variant of SetMyCommands.
+// It executes the same request but uses ctx for cancellation and deadlines.
+// See https://core.telegram.org/bots/api#setmycommands
+func (api *API) SetMyCommandsWithContext(ctx context.Context, params SetMyCommandsP) (bool, error) {
+	req := NewRequest[bool]("setMyCommands", params)
+	return req.DoWithContext(ctx, api)
+}
+
+// DeleteMyCommandsP holds parameters for the deleteMyCommands method.
+// See https://core.telegram.org/bots/api#deletemycommands
+type DeleteMyCommandsP struct {
+	Scope    *BotCommandScope `json:"scope,omitempty"`
+	Language string           `json:"language_code,omitempty"`
+}
+
+// DeleteMyCommands deletes the list of the bot's commands for the given scope and user language.
+// Returns true on success.
+// See https://core.telegram.org/bots/api#deletemycommands
+func (api *API) DeleteMyCommands(params DeleteMyCommandsP) (bool, error) {
+	req := NewRequest[bool]("deleteMyCommands", params)
+	return req.Do(api)
+}
+
+// DeleteMyCommandsWithContext is the context-aware variant of DeleteMyCommands.
+// It executes the same request but uses ctx for cancellation and deadlines.
+// See https://core.telegram.org/bots/api#deletemycommands
+func (api *API) DeleteMyCommandsWithContext(ctx context.Context, params DeleteMyCommandsP) (bool, error) {
+	req := NewRequest[bool]("deleteMyCommands", params)
+	return req.DoWithContext(ctx, api)
+}
+
+// GetMyCommands holds parameters for the getMyCommands method.
+// 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.
+// 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.
+// 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.
+// 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.
+// 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.
+// 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.
+// 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.
+// 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.
+// 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.
+// 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.
+// 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.
+// 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.
+// 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.
+// 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.
+// 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.
+// 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.
+// 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.
+// 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.
+// 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.
+// 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)
+}
+
+// GetMyShortDescriptionWithContext is the context-aware variant of GetMyShortDescription.
+// 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)
+}
+
+// SetMyProfilePhotoP holds parameters for the setMyProfilePhoto method.
+// See https://core.telegram.org/bots/api#setmyprofilephoto
+type SetMyProfilePhotoP struct {
+	Photo InputProfilePhoto `json:"photo"`
+}
+
+// SetMyProfilePhoto changes the bot's profile photo.
+// Returns true on success.
+// See https://core.telegram.org/bots/api#setmyprofilephoto
+func (api *API) SetMyProfilePhoto(params SetMyProfilePhotoP) (bool, error) {
+	req := NewRequest[bool]("setMyProfilePhoto", params)
+	return req.Do(api)
+}
+
+// SetMyProfilePhotoWithContext is the context-aware variant of SetMyProfilePhoto.
+// It executes the same request but uses ctx for cancellation and deadlines.
+// See https://core.telegram.org/bots/api#setmyprofilephoto
+func (api *API) SetMyProfilePhotoWithContext(ctx context.Context, params SetMyProfilePhotoP) (bool, error) {
+	req := NewRequest[bool]("setMyProfilePhoto", params)
+	return req.DoWithContext(ctx, api)
+}
+
+// RemoveMyProfilePhoto removes the bot's profile photo.
+// 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)
+}
+
+// RemoveMyProfilePhotoWithContext is the context-aware variant of RemoveMyProfilePhoto.
+// 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)
+}
+
+// SetChatMenuButtonP holds parameters for the setChatMenuButton method.
+// See https://core.telegram.org/bots/api#setchatmenubutton
+type SetChatMenuButtonP struct {
+	ChatID     int64          `json:"chat_id,omitempty"`
+	MenuButton MenuButtonType `json:"menu_button"`
+}
+
+// SetChatMenuButton changes the menu button for a given chat or the default menu button.
+// Returns true on success.
+// See https://core.telegram.org/bots/api#setchatmenubutton
+func (api *API) SetChatMenuButton(params SetChatMenuButtonP) (bool, error) {
+	req := NewRequest[bool]("setChatMenuButton", params)
+	return req.Do(api)
+}
+
+// SetChatMenuButtonWithContext is the context-aware variant of SetChatMenuButton.
+// It executes the same request but uses ctx for cancellation and deadlines.
+// See https://core.telegram.org/bots/api#setchatmenubutton
+func (api *API) SetChatMenuButtonWithContext(ctx context.Context, params SetChatMenuButtonP) (bool, error) {
+	req := NewRequest[bool]("setChatMenuButton", params)
+	return req.DoWithContext(ctx, api)
+}
+
+// GetChatMenuButtonP holds parameters for the getChatMenuButton method.
+// See https://core.telegram.org/bots/api#getchatmenubutton
+type GetChatMenuButtonP struct {
+	ChatID int64 `json:"chat_id,omitempty"`
+}
+
+// GetChatMenuButton returns the current menu button for the given chat.
+// See https://core.telegram.org/bots/api#getchatmenubutton
+func (api *API) GetChatMenuButton(params GetChatMenuButtonP) (MenuButton, error) {
+	req := NewRequest[MenuButton]("getChatMenuButton", params)
+	return req.Do(api)
+}
+
+// GetChatMenuButtonWithContext is the context-aware variant of GetChatMenuButton.
+// It executes the same request but uses ctx for cancellation and deadlines.
+// See https://core.telegram.org/bots/api#getchatmenubutton
+func (api *API) GetChatMenuButtonWithContext(ctx context.Context, params GetChatMenuButtonP) (MenuButton, error) {
+	req := NewRequest[MenuButton]("getChatMenuButton", params)
+	return req.DoWithContext(ctx, api)
+}
+
+// SetMyDefaultAdministratorRightsP holds parameters for the setMyDefaultAdministratorRights method.
+// See https://core.telegram.org/bots/api#setmydefaultadministratorrights
+type SetMyDefaultAdministratorRightsP struct {
+	Rights      *ChatAdministratorRights `json:"rights"`
+	ForChannels bool                     `json:"for_channels"`
+}
+
+// SetMyDefaultAdministratorRights changes the default administrator rights for the bot.
+// Returns true on success.
+// See https://core.telegram.org/bots/api#setmydefaultadministratorrights
+func (api *API) SetMyDefaultAdministratorRights(params SetMyDefaultAdministratorRightsP) (bool, error) {
+	req := NewRequest[bool]("setMyDefaultAdministratorRights", params)
+	return req.Do(api)
+}
+
+// SetMyDefaultAdministratorRightsWithContext is the context-aware variant of SetMyDefaultAdministratorRights.
+// It executes the same request but uses ctx for cancellation and deadlines.
+// See https://core.telegram.org/bots/api#setmydefaultadministratorrights
+func (api *API) SetMyDefaultAdministratorRightsWithContext(ctx context.Context, params SetMyDefaultAdministratorRightsP) (bool, error) {
+	req := NewRequest[bool]("setMyDefaultAdministratorRights", params)
+	return req.DoWithContext(ctx, api)
+}
+
+// GetMyDefaultAdministratorRightsP holds parameters for the getMyDefaultAdministratorRights method.
+// See https://core.telegram.org/bots/api#getmydefaultadministratorrights
+type GetMyDefaultAdministratorRightsP struct {
+	ForChannels bool `json:"for_channels"`
+}
+
+// GetMyDefaultAdministratorRights returns the current default administrator rights for the bot.
+// See https://core.telegram.org/bots/api#getmydefaultadministratorrights
+func (api *API) GetMyDefaultAdministratorRights(params GetMyDefaultAdministratorRightsP) (ChatAdministratorRights, error) {
+	req := NewRequest[ChatAdministratorRights]("getMyDefaultAdministratorRights", params)
+	return req.Do(api)
+}
+
+// GetMyDefaultAdministratorRightsWithContext is the context-aware variant of GetMyDefaultAdministratorRights.
+// It executes the same request but uses ctx for cancellation and deadlines.
+// See https://core.telegram.org/bots/api#getmydefaultadministratorrights
+func (api *API) GetMyDefaultAdministratorRightsWithContext(ctx context.Context, params GetMyDefaultAdministratorRightsP) (ChatAdministratorRights, error) {
+	req := NewRequest[ChatAdministratorRights]("getMyDefaultAdministratorRights", params)
+	return req.DoWithContext(ctx, api)
+}
+
+// GetAvailableGifts returns the list of gifts that can be sent by the bot.
+// See https://core.telegram.org/bots/api#getavailablegifts
+func (api *API) GetAvailableGifts() (Gifts, error) {
+	req := NewRequest[Gifts]("getAvailableGifts", NoParams)
+	return req.Do(api)
+}
+
+// GetAvailableGiftsWithContext is the context-aware variant of GetAvailableGifts.
+// 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)
+}
+
+// SendGiftP holds parameters for the sendGift method.
+// See https://core.telegram.org/bots/api#sendgift
+type SendGiftP 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"`
+	TextParseMode ParseMode       `json:"text_parse_mode,omitempty"`
+	TextEntities  []MessageEntity `json:"text_entities,omitempty"`
+}
+
+// SendGift sends a gift to the given user or chat.
+// Returns true on success.
+// See https://core.telegram.org/bots/api#sendgift
+func (api *API) SendGift(params SendGiftP) (bool, error) {
+	req := NewRequest[bool]("sendGift", params)
+	return req.Do(api)
+}
+
+// SendGiftWithContext is the context-aware variant of SendGift.
+// It executes the same request but uses ctx for cancellation and deadlines.
+// See https://core.telegram.org/bots/api#sendgift
+func (api *API) SendGiftWithContext(ctx context.Context, params SendGiftP) (bool, error) {
+	req := NewRequest[bool]("sendGift", params)
+	return req.DoWithContext(ctx, api)
+}
+
+// GiftPremiumSubscriptionP holds parameters for the giftPremiumSubscription method.
+// See https://core.telegram.org/bots/api#giftpremiumsubscription
+type GiftPremiumSubscriptionP struct {
+	UserID        int64           `json:"user_id"`
+	MonthCount    int             `json:"month_count"`
+	StarCount     int             `json:"star_count"`
+	Text          string          `json:"text,omitempty"`
+	TextParseMode ParseMode       `json:"text_parse_mode,omitempty"`
+	TextEntities  []MessageEntity `json:"text_entities,omitempty"`
+}
+
+// GiftPremiumSubscription gifts a Telegram Premium subscription to the user.
+// Returns true on success.
+// See https://core.telegram.org/bots/api#giftpremiumsubscription
+func (api *API) GiftPremiumSubscription(params GiftPremiumSubscriptionP) (bool, error) {
+	req := NewRequest[bool]("giftPremiumSubscription", params)
+	return req.Do(api)
+}
+
+// GiftPremiumSubscriptionWithContext is the context-aware variant of GiftPremiumSubscription.
+// It executes the same request but uses ctx for cancellation and deadlines.
+// See https://core.telegram.org/bots/api#giftpremiumsubscription
+func (api *API) GiftPremiumSubscriptionWithContext(ctx context.Context, params GiftPremiumSubscriptionP) (bool, error) {
+	req := NewRequest[bool]("giftPremiumSubscription", params)
+	return req.DoWithContext(ctx, api)
+}

tgapi/bot_types.go

@@ -0,0 +1,96 @@
+package tgapi
+
+// BotCommand represents a bot command.
+// See https://core.telegram.org/bots/api#botcommand
+type BotCommand struct {
+	Command     string `json:"command"`
+	Description string `json:"description"`
+}
+
+// BotCommandScopeType indicates the type of a command scope.
+type BotCommandScopeType string
+
+const (
+	// 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 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.
+// See https://core.telegram.org/bots/api#botcommandscope
+type BotCommandScope struct {
+	Type   BotCommandScopeType `json:"type"`
+	ChatID *int64              `json:"chat_id,omitempty"`
+	UserID *int64              `json:"user_id,omitempty"`
+}
+
+// BotName represents the bot's name.
+type BotName struct {
+	Name string `json:"name"`
+}
+
+// BotDescription represents the bot's description.
+type BotDescription struct {
+	Description string `json:"description"`
+}
+
+// BotShortDescription represents the bot's short description.
+type BotShortDescription struct {
+	ShortDescription string `json:"short_description"`
+}
+
+// InputProfilePhotoType indicates the type of a profile photo input.
+type InputProfilePhotoType string
+
+const (
+	// InputProfilePhotoStaticType identifies a static profile photo input.
+	InputProfilePhotoStaticType InputProfilePhotoType = "static"
+	// InputProfilePhotoAnimatedType identifies an animated profile photo input.
+	InputProfilePhotoAnimatedType InputProfilePhotoType = "animated"
+)
+
+// InputProfilePhoto describes a profile photo to set.
+// See https://core.telegram.org/bots/api#inputprofilephoto
+type InputProfilePhoto struct {
+	Type InputProfilePhotoType `json:"type"`
+
+	// Static fields (for static photos)
+	Photo *string `json:"photo,omitempty"`
+
+	// 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 identifies a web app menu button.
+	MenuButtonWebAppType MenuButtonType = "web_app"
+	// MenuButtonDefaultType identifies Telegram's default menu button.
+	MenuButtonDefaultType MenuButtonType = "default"
+)
+
+// MenuButton represents a menu button.
+// See https://core.telegram.org/bots/api#menubutton
+type MenuButton struct {
+	Type MenuButtonType `json:"type"`
+
+	// WebApp fields (for web_app button)
+	Text   *string     `json:"text"`
+	WebApp *WebAppInfo `json:"web_app"`
+}

tgapi/business_methods.go

@@ -0,0 +1,575 @@
+package tgapi
+
+import "context"
+
+// VerifyUserP holds parameters for the verifyUser method.
+// See https://core.telegram.org/bots/api#verifyuser
+type VerifyUserP struct {
+	UserID            int64  `json:"user_id"`
+	CustomDescription string `json:"custom_description,omitempty"`
+}
+
+// VerifyUser verifies a user.
+// Returns true on success.
+// See https://core.telegram.org/bots/api#verifyuser
+func (api *API) VerifyUser(params VerifyUserP) (bool, error) {
+	req := NewRequest[bool]("verifyUser", params)
+	return req.Do(api)
+}
+
+// VerifyUserWithContext is the context-aware variant of VerifyUser.
+// It executes the same request but uses ctx for cancellation and deadlines.
+// See https://core.telegram.org/bots/api#verifyuser
+func (api *API) VerifyUserWithContext(ctx context.Context, params VerifyUserP) (bool, error) {
+	req := NewRequest[bool]("verifyUser", params)
+	return req.DoWithContext(ctx, api)
+}
+
+// VerifyChatP holds parameters for the verifyChat method.
+// See https://core.telegram.org/bots/api#verifychat
+type VerifyChatP struct {
+	ChatID            int64  `json:"chat_id"`
+	CustomDescription string `json:"custom_description,omitempty"`
+}
+
+// VerifyChat verifies a chat.
+// Returns true on success.
+// See https://core.telegram.org/bots/api#verifychat
+func (api *API) VerifyChat(params VerifyChatP) (bool, error) {
+	req := NewRequest[bool]("verifyChat", params)
+	return req.Do(api)
+}
+
+// VerifyChatWithContext is the context-aware variant of VerifyChat.
+// It executes the same request but uses ctx for cancellation and deadlines.
+// See https://core.telegram.org/bots/api#verifychat
+func (api *API) VerifyChatWithContext(ctx context.Context, params VerifyChatP) (bool, error) {
+	req := NewRequest[bool]("verifyChat", params)
+	return req.DoWithContext(ctx, api)
+}
+
+// RemoveUserVerificationP holds parameters for the removeUserVerification method.
+// See https://core.telegram.org/bots/api#removeuserverification
+type RemoveUserVerificationP struct {
+	UserID int64 `json:"user_id"`
+}
+
+// RemoveUserVerification removes a user's verification.
+// Returns true on success.
+// See https://core.telegram.org/bots/api#removeuserverification
+func (api *API) RemoveUserVerification(params RemoveUserVerificationP) (bool, error) {
+	req := NewRequest[bool]("removeUserVerification", params)
+	return req.Do(api)
+}
+
+// RemoveUserVerificationWithContext is the context-aware variant of RemoveUserVerification.
+// It executes the same request but uses ctx for cancellation and deadlines.
+// See https://core.telegram.org/bots/api#removeuserverification
+func (api *API) RemoveUserVerificationWithContext(ctx context.Context, params RemoveUserVerificationP) (bool, error) {
+	req := NewRequest[bool]("removeUserVerification", params)
+	return req.DoWithContext(ctx, api)
+}
+
+// RemoveChatVerificationP holds parameters for the removeChatVerification method.
+// See https://core.telegram.org/bots/api#removechatverification
+type RemoveChatVerificationP struct {
+	ChatID int64 `json:"chat_id"`
+}
+
+// RemoveChatVerification removes a chat's verification.
+// Returns true on success.
+// See https://core.telegram.org/bots/api#removechatverification
+func (api *API) RemoveChatVerification(params RemoveChatVerificationP) (bool, error) {
+	req := NewRequest[bool]("removeChatVerification", params)
+	return req.Do(api)
+}
+
+// RemoveChatVerificationWithContext is the context-aware variant of RemoveChatVerification.
+// It executes the same request but uses ctx for cancellation and deadlines.
+// See https://core.telegram.org/bots/api#removechatverification
+func (api *API) RemoveChatVerificationWithContext(ctx context.Context, params RemoveChatVerificationP) (bool, error) {
+	req := NewRequest[bool]("removeChatVerification", params)
+	return req.DoWithContext(ctx, api)
+}
+
+// ReadBusinessMessageP holds parameters for the readBusinessMessage method.
+// See https://core.telegram.org/bots/api#readbusinessmessage
+type ReadBusinessMessageP struct {
+	BusinessConnectionID string `json:"business_connection_id"`
+	ChatID               int64  `json:"chat_id"`
+	MessageID            int    `json:"message_id"`
+}
+
+// ReadBusinessMessage marks a business message as read.
+// Returns true on success.
+// See https://core.telegram.org/bots/api#readbusinessmessage
+func (api *API) ReadBusinessMessage(params ReadBusinessMessageP) (bool, error) {
+	req := NewRequest[bool]("readBusinessMessage", params)
+	return req.Do(api)
+}
+
+// ReadBusinessMessageWithContext is the context-aware variant of ReadBusinessMessage.
+// It executes the same request but uses ctx for cancellation and deadlines.
+// See https://core.telegram.org/bots/api#readbusinessmessage
+func (api *API) ReadBusinessMessageWithContext(ctx context.Context, params ReadBusinessMessageP) (bool, error) {
+	req := NewRequest[bool]("readBusinessMessage", params)
+	return req.DoWithContext(ctx, api)
+}
+
+// GetBusinessConnectionP holds parameters for the getBusinessConnection method.
+// See https://core.telegram.org/bots/api#getbusinessconnection
+type GetBusinessConnectionP struct {
+	BusinessConnectionID string `json:"business_connection_id"`
+}
+
+// GetBusinessConnection returns information about a business connection.
+// See https://core.telegram.org/bots/api#getbusinessconnection
+func (api *API) GetBusinessConnection(params GetBusinessConnectionP) (BusinessConnection, error) {
+	req := NewRequest[BusinessConnection]("getBusinessConnection", params)
+	return req.Do(api)
+}
+
+// GetBusinessConnectionWithContext is the context-aware variant of GetBusinessConnection.
+// It executes the same request but uses ctx for cancellation and deadlines.
+// See https://core.telegram.org/bots/api#getbusinessconnection
+func (api *API) GetBusinessConnectionWithContext(ctx context.Context, params GetBusinessConnectionP) (BusinessConnection, error) {
+	req := NewRequest[BusinessConnection]("getBusinessConnection", params)
+	return req.DoWithContext(ctx, api)
+}
+
+// DeleteBusinessMessagesP holds parameters for the deleteBusinessMessages method.
+// See https://core.telegram.org/bots/api#deletebusinessmessages
+type DeleteBusinessMessagesP struct {
+	BusinessConnectionID string `json:"business_connection_id"`
+	MessageIDs           []int  `json:"message_ids"`
+}
+
+// DeleteBusinessMessages deletes business messages.
+// Returns true on success.
+// See https://core.telegram.org/bots/api#deletebusinessmessages
+func (api *API) DeleteBusinessMessages(params DeleteBusinessMessagesP) (bool, error) {
+	req := NewRequest[bool]("deleteBusinessMessages", params)
+	return req.Do(api)
+}
+
+// DeleteBusinessMessagesWithContext is the context-aware variant of DeleteBusinessMessages.
+// It executes the same request but uses ctx for cancellation and deadlines.
+// See https://core.telegram.org/bots/api#deletebusinessmessages
+func (api *API) DeleteBusinessMessagesWithContext(ctx context.Context, params DeleteBusinessMessagesP) (bool, error) {
+	req := NewRequest[bool]("deleteBusinessMessages", params)
+	return req.DoWithContext(ctx, api)
+}
+
+// SetBusinessAccountNameP holds parameters for the setBusinessAccountName method.
+// See https://core.telegram.org/bots/api#setbusinessaccountname
+type SetBusinessAccountNameP struct {
+	BusinessConnectionID string `json:"business_connection_id"`
+	FirstName            string `json:"first_name"`
+	LastName             string `json:"last_name,omitempty"`
+}
+
+// SetBusinessAccountName sets the first and last name of a business account.
+// Returns true on success.
+// See https://core.telegram.org/bots/api#setbusinessaccountname
+func (api *API) SetBusinessAccountName(params SetBusinessAccountNameP) (bool, error) {
+	req := NewRequest[bool]("setBusinessAccountName", params)
+	return req.Do(api)
+}
+
+// SetBusinessAccountNameWithContext is the context-aware variant of SetBusinessAccountName.
+// It executes the same request but uses ctx for cancellation and deadlines.
+// See https://core.telegram.org/bots/api#setbusinessaccountname
+func (api *API) SetBusinessAccountNameWithContext(ctx context.Context, params SetBusinessAccountNameP) (bool, error) {
+	req := NewRequest[bool]("setBusinessAccountName", params)
+	return req.DoWithContext(ctx, api)
+}
+
+// SetBusinessAccountUsernameP holds parameters for the setBusinessAccountUsername method.
+// See https://core.telegram.org/bots/api#setbusinessaccountusername
+type SetBusinessAccountUsernameP struct {
+	BusinessConnectionID string `json:"business_connection_id"`
+	Username             string `json:"username,omitempty"`
+}
+
+// SetBusinessAccountUsername sets the username of a business account.
+// Returns true on success.
+// See https://core.telegram.org/bots/api#setbusinessaccountusername
+func (api *API) SetBusinessAccountUsername(params SetBusinessAccountUsernameP) (bool, error) {
+	req := NewRequest[bool]("setBusinessAccountUsername", params)
+	return req.Do(api)
+}
+
+// SetBusinessAccountUsernameWithContext is the context-aware variant of SetBusinessAccountUsername.
+// It executes the same request but uses ctx for cancellation and deadlines.
+// See https://core.telegram.org/bots/api#setbusinessaccountusername
+func (api *API) SetBusinessAccountUsernameWithContext(ctx context.Context, params SetBusinessAccountUsernameP) (bool, error) {
+	req := NewRequest[bool]("setBusinessAccountUsername", params)
+	return req.DoWithContext(ctx, api)
+}
+
+// SetBusinessAccountBioP holds parameters for the setBusinessAccountBio method.
+// See https://core.telegram.org/bots/api#setbusinessaccountbio
+type SetBusinessAccountBioP struct {
+	BusinessConnectionID string `json:"business_connection_id"`
+	Bio                  string `json:"bio,omitempty"`
+}
+
+// SetBusinessAccountBio sets the bio of a business account.
+// Returns true on success.
+// See https://core.telegram.org/bots/api#setbusinessaccountbio
+func (api *API) SetBusinessAccountBio(params SetBusinessAccountBioP) (bool, error) {
+	req := NewRequest[bool]("setBusinessAccountBio", params)
+	return req.Do(api)
+}
+
+// SetBusinessAccountBioWithContext is the context-aware variant of SetBusinessAccountBio.
+// It executes the same request but uses ctx for cancellation and deadlines.
+// See https://core.telegram.org/bots/api#setbusinessaccountbio
+func (api *API) SetBusinessAccountBioWithContext(ctx context.Context, params SetBusinessAccountBioP) (bool, error) {
+	req := NewRequest[bool]("setBusinessAccountBio", params)
+	return req.DoWithContext(ctx, api)
+}
+
+// SetBusinessAccountProfilePhoto holds parameters for the setBusinessAccountProfilePhoto method.
+// 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.
+// 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)
+}
+
+// SetBusinessAccountProfilePhotoWithContext is the context-aware variant of SetBusinessAccountProfilePhoto.
+// 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)
+}
+
+// RemoveBusinessAccountProfilePhotoP holds parameters for the removeBusinessAccountProfilePhoto method.
+// See https://core.telegram.org/bots/api#removebusinessaccountprofilephoto
+type RemoveBusinessAccountProfilePhotoP struct {
+	BusinessConnectionID string `json:"business_connection_id"`
+	IsPublic             bool   `json:"is_public,omitempty"`
+}
+
+// RemoveBusinessAccountProfilePhoto removes the profile photo of a business account.
+// Returns true on success.
+// See https://core.telegram.org/bots/api#removebusinessaccountprofilephoto
+func (api *API) RemoveBusinessAccountProfilePhoto(params RemoveBusinessAccountProfilePhotoP) (bool, error) {
+	req := NewRequest[bool]("removeBusinessAccountProfilePhoto", params)
+	return req.Do(api)
+}
+
+// RemoveBusinessAccountProfilePhotoWithContext is the context-aware variant of RemoveBusinessAccountProfilePhoto.
+// It executes the same request but uses ctx for cancellation and deadlines.
+// See https://core.telegram.org/bots/api#removebusinessaccountprofilephoto
+func (api *API) RemoveBusinessAccountProfilePhotoWithContext(ctx context.Context, params RemoveBusinessAccountProfilePhotoP) (bool, error) {
+	req := NewRequest[bool]("removeBusinessAccountProfilePhoto", params)
+	return req.DoWithContext(ctx, api)
+}
+
+// SetBusinessAccountGiftSettingsP holds parameters for the setBusinessAccountGiftSettings method.
+// See https://core.telegram.org/bots/api#setbusinessaccountgiftsettings
+type SetBusinessAccountGiftSettingsP struct {
+	BusinessConnectionID string            `json:"business_connection_id"`
+	ShowGiftButton       bool              `json:"show_gift_button"`
+	AcceptedGiftTypes    AcceptedGiftTypes `json:"accepted_gift_types"`
+}
+
+// SetBusinessAccountGiftSettings sets gift settings for a business account.
+// Returns true on success.
+// See https://core.telegram.org/bots/api#setbusinessaccountgiftsettings
+func (api *API) SetBusinessAccountGiftSettings(params SetBusinessAccountGiftSettingsP) (bool, error) {
+	req := NewRequest[bool]("setBusinessAccountGiftSettings", params)
+	return req.Do(api)
+}
+
+// SetBusinessAccountGiftSettingsWithContext is the context-aware variant of SetBusinessAccountGiftSettings.
+// It executes the same request but uses ctx for cancellation and deadlines.
+// See https://core.telegram.org/bots/api#setbusinessaccountgiftsettings
+func (api *API) SetBusinessAccountGiftSettingsWithContext(ctx context.Context, params SetBusinessAccountGiftSettingsP) (bool, error) {
+	req := NewRequest[bool]("setBusinessAccountGiftSettings", params)
+	return req.DoWithContext(ctx, api)
+}
+
+// GetBusinessAccountStarBalanceP holds parameters for the getBusinessAccountStarBalance method.
+// See https://core.telegram.org/bots/api#getbusinessaccountstarbalance
+type GetBusinessAccountStarBalanceP struct {
+	BusinessConnectionID string `json:"business_connection_id"`
+}
+
+// GetBusinessAccountStarBalance returns the star balance of a business account.
+// See https://core.telegram.org/bots/api#getbusinessaccountstarbalance
+func (api *API) GetBusinessAccountStarBalance(params GetBusinessAccountStarBalanceP) (StarAmount, error) {
+	req := NewRequest[StarAmount]("getBusinessAccountStarBalance", params)
+	return req.Do(api)
+}
+
+// GetBusinessAccountStarBalanceWithContext is the context-aware variant of GetBusinessAccountStarBalance.
+// It executes the same request but uses ctx for cancellation and deadlines.
+// See https://core.telegram.org/bots/api#getbusinessaccountstarbalance
+func (api *API) GetBusinessAccountStarBalanceWithContext(ctx context.Context, params GetBusinessAccountStarBalanceP) (StarAmount, error) {
+	req := NewRequest[StarAmount]("getBusinessAccountStarBalance", params)
+	return req.DoWithContext(ctx, api)
+}
+
+// TransferBusinessAccountStarsP holds parameters for the transferBusinessAccountStars method.
+// See https://core.telegram.org/bots/api#transferbusinessaccountstars
+type TransferBusinessAccountStarsP struct {
+	BusinessConnectionID string `json:"business_connection_id"`
+	StarCount            int    `json:"star_count"`
+}
+
+// TransferBusinessAccountStars transfers stars from a business account.
+// Returns true on success.
+// See https://core.telegram.org/bots/api#transferbusinessaccountstars
+func (api *API) TransferBusinessAccountStars(params TransferBusinessAccountStarsP) (bool, error) {
+	req := NewRequest[bool]("transferBusinessAccountStars", params)
+	return req.Do(api)
+}
+
+// TransferBusinessAccountStarsWithContext is the context-aware variant of TransferBusinessAccountStars.
+// It executes the same request but uses ctx for cancellation and deadlines.
+// See https://core.telegram.org/bots/api#transferbusinessaccountstars
+func (api *API) TransferBusinessAccountStarsWithContext(ctx context.Context, params TransferBusinessAccountStarsP) (bool, error) {
+	req := NewRequest[bool]("transferBusinessAccountStars", params)
+	return req.DoWithContext(ctx, api)
+}
+
+// GetBusinessAccountGiftsP holds parameters for the getBusinessAccountGifts method.
+// See https://core.telegram.org/bots/api#getbusinessaccountgifts
+type GetBusinessAccountGiftsP struct {
+	BusinessConnectionID        string `json:"business_connection_id"`
+	ExcludeUnsaved              bool   `json:"exclude_unsaved,omitempty"`
+	ExcludeSaved                bool   `json:"exclude_saved,omitempty"`
+	ExcludeUnlimited            bool   `json:"exclude_unlimited,omitempty"`
+	ExcludeLimitedUpgradable    bool   `json:"exclude_limited_upgradable,omitempty"`
+	ExcludeLimitedNonUpgradable bool   `json:"exclude_limited_non_upgradable,omitempty"`
+	ExcludeUnique               bool   `json:"exclude_unique,omitempty"`
+	ExcludeFromBlockchain       bool   `json:"exclude_from_blockchain,omitempty"`
+	SortByPrice                 bool   `json:"sort_by_price,omitempty"`
+	Offset                      string `json:"offset,omitempty"`
+	Limit                       int    `json:"limit,omitempty"`
+}
+
+// GetBusinessAccountGifts returns gifts owned by a business account.
+// See https://core.telegram.org/bots/api#getbusinessaccountgifts
+func (api *API) GetBusinessAccountGifts(params GetBusinessAccountGiftsP) (OwnedGifts, error) {
+	req := NewRequest[OwnedGifts]("getBusinessAccountGifts", params)
+	return req.Do(api)
+}
+
+// GetBusinessAccountGiftsWithContext is the context-aware variant of GetBusinessAccountGifts.
+// It executes the same request but uses ctx for cancellation and deadlines.
+// See https://core.telegram.org/bots/api#getbusinessaccountgifts
+func (api *API) GetBusinessAccountGiftsWithContext(ctx context.Context, params GetBusinessAccountGiftsP) (OwnedGifts, error) {
+	req := NewRequest[OwnedGifts]("getBusinessAccountGifts", params)
+	return req.DoWithContext(ctx, api)
+}
+
+// ConvertGiftToStarsP holds parameters for the convertGiftToStars method.
+// See https://core.telegram.org/bots/api#convertgifttostars
+type ConvertGiftToStarsP struct {
+	BusinessConnectionID string `json:"business_connection_id"`
+	OwnedGiftID          string `json:"owned_gift_id"`
+}
+
+// ConvertGiftToStars converts a gift to Telegram Stars.
+// Returns true on success.
+// See https://core.telegram.org/bots/api#convertgifttostars
+func (api *API) ConvertGiftToStars(params ConvertGiftToStarsP) (bool, error) {
+	req := NewRequest[bool]("convertGiftToStars", params)
+	return req.Do(api)
+}
+
+// ConvertGiftToStarsWithContext is the context-aware variant of ConvertGiftToStars.
+// It executes the same request but uses ctx for cancellation and deadlines.
+// See https://core.telegram.org/bots/api#convertgifttostars
+func (api *API) ConvertGiftToStarsWithContext(ctx context.Context, params ConvertGiftToStarsP) (bool, error) {
+	req := NewRequest[bool]("convertGiftToStars", params)
+	return req.DoWithContext(ctx, api)
+}
+
+// UpgradeGiftP holds parameters for the upgradeGift method.
+// See https://core.telegram.org/bots/api#upgradegift
+type UpgradeGiftP 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"`
+}
+
+// UpgradeGift upgrades a gift.
+// Returns true on success.
+// See https://core.telegram.org/bots/api#upgradegift
+func (api *API) UpgradeGift(params UpgradeGiftP) (bool, error) {
+	req := NewRequest[bool]("upgradeGift", params)
+	return req.Do(api)
+}
+
+// UpgradeGiftWithContext is the context-aware variant of UpgradeGift.
+// It executes the same request but uses ctx for cancellation and deadlines.
+// See https://core.telegram.org/bots/api#upgradegift
+func (api *API) UpgradeGiftWithContext(ctx context.Context, params UpgradeGiftP) (bool, error) {
+	req := NewRequest[bool]("upgradeGift", params)
+	return req.DoWithContext(ctx, api)
+}
+
+// TransferGiftP holds parameters for the transferGift method.
+// See https://core.telegram.org/bots/api#transfergift
+type TransferGiftP struct {
+	BusinessConnectionID string `json:"business_connection_id"`
+	OwnedGiftID          string `json:"owned_gift_id"`
+	NewOwnerChatID       int64  `json:"new_owner_chat_id"`
+	StarCount            int    `json:"star_count,omitempty"`
+}
+
+// TransferGift transfers a gift to another chat.
+// Returns true on success.
+// See https://core.telegram.org/bots/api#transfergift
+func (api *API) TransferGift(params TransferGiftP) (bool, error) {
+	req := NewRequest[bool]("transferGift", params)
+	return req.Do(api)
+}
+
+// TransferGiftWithContext is the context-aware variant of TransferGift.
+// It executes the same request but uses ctx for cancellation and deadlines.
+// See https://core.telegram.org/bots/api#transfergift
+func (api *API) TransferGiftWithContext(ctx context.Context, params TransferGiftP) (bool, error) {
+	req := NewRequest[bool]("transferGift", params)
+	return req.DoWithContext(ctx, api)
+}
+
+// PostStoryP holds parameters for the postStory method.
+// See https://core.telegram.org/bots/api#poststory
+type PostStoryP struct {
+	BusinessConnectionID string            `json:"business_connection_id"`
+	Content              InputStoryContent `json:"content"`
+	ActivePeriod         int               `json:"active_period"`
+
+	Caption         string          `json:"caption,omitempty"`
+	ParseMode       ParseMode       `json:"parse_mode,omitempty"`
+	CaptionEntities []MessageEntity `json:"caption_entities,omitempty"`
+	Areas           []StoryArea     `json:"areas"`
+
+	PostToChatPage bool `json:"post_to_chat_page,omitempty"`
+	ProtectContent bool `json:"protect_content,omitempty"`
+}
+
+// PostStoryPhoto posts a story with a photo.
+// See https://core.telegram.org/bots/api#poststory
+func (api *API) PostStoryPhoto(params PostStoryP) (Story, error) {
+	req := NewRequest[Story]("postStory", params)
+	return req.Do(api)
+}
+
+// PostStoryPhotoWithContext is the context-aware variant of PostStoryPhoto.
+// It executes the same request but uses ctx for cancellation and deadlines.
+// See https://core.telegram.org/bots/api#poststory
+func (api *API) PostStoryPhotoWithContext(ctx context.Context, params PostStoryP) (Story, error) {
+	req := NewRequest[Story]("postStory", params)
+	return req.DoWithContext(ctx, api)
+}
+
+// PostStoryVideo posts a story with a video.
+// See https://core.telegram.org/bots/api#poststory
+func (api *API) PostStoryVideo(params PostStoryP) (Story, error) {
+	req := NewRequest[Story]("postStory", params)
+	return req.Do(api)
+}
+
+// PostStoryVideoWithContext is the context-aware variant of PostStoryVideo.
+// It executes the same request but uses ctx for cancellation and deadlines.
+// See https://core.telegram.org/bots/api#poststory
+func (api *API) PostStoryVideoWithContext(ctx context.Context, params PostStoryP) (Story, error) {
+	req := NewRequest[Story]("postStory", params)
+	return req.DoWithContext(ctx, api)
+}
+
+// RepostStoryP holds parameters for the repostStory method.
+// See https://core.telegram.org/bots/api#repoststory
+type RepostStoryP struct {
+	BusinessConnectionID string `json:"business_connection_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"`
+}
+
+// RepostStory reposts a story from another chat.
+// Returns the reposted story.
+// See https://core.telegram.org/bots/api#repoststory
+func (api *API) RepostStory(params RepostStoryP) (Story, error) {
+	req := NewRequest[Story]("repostStory", params)
+	return req.Do(api)
+}
+
+// RepostStoryWithContext is the context-aware variant of RepostStory.
+// It executes the same request but uses ctx for cancellation and deadlines.
+// See https://core.telegram.org/bots/api#repoststory
+func (api *API) RepostStoryWithContext(ctx context.Context, params RepostStoryP) (Story, error) {
+	req := NewRequest[Story]("repostStory", params)
+	return req.DoWithContext(ctx, api)
+}
+
+// EditStoryP holds parameters for the editStory method.
+// See https://core.telegram.org/bots/api#editstory
+type EditStoryP struct {
+	BusinessConnectionID string            `json:"business_connection_id"`
+	StoryID              int               `json:"story_id"`
+	Content              InputStoryContent `json:"content"`
+
+	Caption         string          `json:"caption,omitempty"`
+	ParseMode       ParseMode       `json:"parse_mode,omitempty"`
+	CaptionEntities []MessageEntity `json:"caption_entities,omitempty"`
+	Areas           []StoryArea     `json:"areas,omitempty"`
+}
+
+// EditStory edits an existing story.
+// Returns the updated story.
+// See https://core.telegram.org/bots/api#editstory
+func (api *API) EditStory(params EditStoryP) (Story, error) {
+	req := NewRequest[Story]("editStory", params)
+	return req.Do(api)
+}
+
+// EditStoryWithContext is the context-aware variant of EditStory.
+// It executes the same request but uses ctx for cancellation and deadlines.
+// See https://core.telegram.org/bots/api#editstory
+func (api *API) EditStoryWithContext(ctx context.Context, params EditStoryP) (Story, error) {
+	req := NewRequest[Story]("editStory", params)
+	return req.DoWithContext(ctx, api)
+}
+
+// DeleteStoryP holds parameters for the deleteStory method.
+// See https://core.telegram.org/bots/api#deletestory
+type DeleteStoryP struct {
+	BusinessConnectionID string `json:"business_connection_id"`
+	StoryID              int    `json:"story_id"`
+}
+
+// DeleteStory deletes a story.
+// Returns true on success.
+// See https://core.telegram.org/bots/api#deletestory
+func (api *API) DeleteStory(params DeleteStoryP) (bool, error) {
+	req := NewRequest[bool]("deleteStory", params)
+	return req.Do(api)
+}
+
+// DeleteStoryWithContext is the context-aware variant of DeleteStory.
+// It executes the same request but uses ctx for cancellation and deadlines.
+// See https://core.telegram.org/bots/api#deletestory
+func (api *API) DeleteStoryWithContext(ctx context.Context, params DeleteStoryP) (bool, error) {
+	req := NewRequest[bool]("deleteStory", params)
+	return req.DoWithContext(ctx, api)
+}

tgapi/business_types.go

@@ -0,0 +1,156 @@
+package tgapi
+
+// BusinessIntro contains information about the business intro.
+// 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.
+// 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.
+// 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.
+// See https://core.telegram.org/bots/api#businessopeninghours
+type BusinessOpeningHours struct {
+	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.
+// See https://core.telegram.org/bots/api#businessbotrights
+type BusinessBotRights struct {
+	CanReply                   *bool `json:"can_reply,omitempty"`
+	CanReadMessages            *bool `json:"can_read_messages,omitempty"`
+	CanDeleteSentMessages      *bool `json:"can_delete_sent_messages,omitempty"`
+	CanDeleteAllMessages       *bool `json:"can_delete_all_messages,omitempty"`
+	CanEditName                *bool `json:"can_edit_name,omitempty"`
+	CanEditBio                 *bool `json:"can_edit_bio,omitempty"`
+	CanEditProfilePhoto        *bool `json:"can_edit_profile_photo,omitempty"`
+	CanEditUsername            *bool `json:"can_edit_username,omitempty"`
+	CanChangeGiftSettings      *bool `json:"can_change_gift_settings,omitempty"`
+	CanViewGiftsAndStars       *bool `json:"can_view_gifts_and_stars,omitempty"`
+	CanConvertGiftsToStars     *bool `json:"can_convert_gifts_to_stars,omitempty"`
+	CanTransferAndUpgradeGifts *bool `json:"can_transfer_and_upgrade_gifts,omitempty"`
+	CanTransferStars           *bool `json:"can_transfer_stars,omitempty"`
+	CanManageStories           *bool `json:"can_manage_stories,omitempty"`
+}
+
+// BusinessConnection contains information about a business connection.
+// See https://core.telegram.org/bots/api#businessconnection
+type BusinessConnection struct {
+	ID         string             `json:"id"`
+	User       User               `json:"user"`
+	UserChatID int64              `json:"user_chat_id"`
+	Date       int                `json:"date"`
+	Rights     *BusinessBotRights `json:"rights,omitempty"`
+	IsEnabled  bool               `json:"is_enabled"`
+}
+
+// BusinessMessagesDeleted is received when messages are deleted from a connected business account.
+// 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"
+)
+
+// InputStoryContent represents the content of a story to be posted.
+// See https://core.telegram.org/bots/api#inputstorycontent
+type InputStoryContent struct {
+	Type InputStoryContentType `json:"type"`
+
+	// Photo fields
+	Photo *string `json:"photo,omitempty"`
+
+	// 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.
+// See https://core.telegram.org/bots/api#storyareaposition
+type StoryAreaPosition struct {
+	XPercentage            float64 `json:"x_percentage"`
+	YPercentage            float64 `json:"y_percentage"`
+	WidthPercentage        float64 `json:"width_percentage"`
+	HeightPercentage       float64 `json:"height_percentage"`
+	RotationAngle          float64 `json:"rotation_angle"`
+	CornerRadiusPercentage float64 `json:"corner_radius_percentage"`
+}
+
+// StoryAreaTypeType indicates the type of story area.
+type StoryAreaTypeType string
+
+const (
+	// 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"
+)
+
+// StoryAreaType describes the type of a clickable area on a story.
+// Fields should be set according to the Type.
+// 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,omitempty"`
+	BackgroundColor *int     `json:"background_color,omitempty"`
+
+	// Unique gift
+	Name *string `json:"name,omitempty"`
+}
+
+// StoryArea represents a clickable area on a story.
+// See https://core.telegram.org/bots/api#storyarea
+type StoryArea struct {
+	Position StoryAreaPosition `json:"position"`
+	Type     StoryAreaType     `json:"type"`
+}

tgapi/chat_methods.go

@@ -0,0 +1,794 @@
+package tgapi
+
+import "context"
+
+// BanChatMemberP holds parameters for the banChatMember method.
+// See https://core.telegram.org/bots/api#banchatmember
+type BanChatMemberP struct {
+	ChatID         int64 `json:"chat_id"`
+	UserID         int64 `json:"user_id"`
+	UntilDate      int   `json:"until_date,omitempty"`
+	RevokeMessages bool  `json:"revoke_messages,omitempty"`
+}
+
+// BanChatMember bans a user in a chat.
+// Returns True on success.
+// See https://core.telegram.org/bots/api#banchatmember
+func (api *API) BanChatMember(params BanChatMemberP) (bool, error) {
+	req := NewRequestWithChatID[bool]("banChatMember", params, params.ChatID)
+	return req.Do(api)
+}
+
+// BanChatMemberWithContext is the context-aware variant of BanChatMember.
+// It executes the same request but uses ctx for cancellation and deadlines.
+// See https://core.telegram.org/bots/api#banchatmember
+func (api *API) BanChatMemberWithContext(ctx context.Context, params BanChatMemberP) (bool, error) {
+	req := NewRequestWithChatID[bool]("banChatMember", params, params.ChatID)
+	return req.DoWithContext(ctx, api)
+}
+
+// UnbanChatMemberP holds parameters for the unbanChatMember method.
+// See https://core.telegram.org/bots/api#unbanchatmember
+type UnbanChatMemberP struct {
+	ChatID       int64 `json:"chat_id"`
+	UserID       int64 `json:"user_id"`
+	OnlyIfBanned bool  `json:"only_if_banned"`
+}
+
+// UnbanChatMember unbans a previously banned user in a chat.
+// Returns True on success.
+// See https://core.telegram.org/bots/api#unbanchatmember
+func (api *API) UnbanChatMember(params UnbanChatMemberP) (bool, error) {
+	req := NewRequestWithChatID[bool]("unbanChatMember", params, params.ChatID)
+	return req.Do(api)
+}
+
+// UnbanChatMemberWithContext is the context-aware variant of UnbanChatMember.
+// It executes the same request but uses ctx for cancellation and deadlines.
+// See https://core.telegram.org/bots/api#unbanchatmember
+func (api *API) UnbanChatMemberWithContext(ctx context.Context, params UnbanChatMemberP) (bool, error) {
+	req := NewRequestWithChatID[bool]("unbanChatMember", params, params.ChatID)
+	return req.DoWithContext(ctx, api)
+}
+
+// RestrictChatMemberP holds parameters for the restrictChatMember method.
+// See https://core.telegram.org/bots/api#restrictchatmember
+type RestrictChatMemberP struct {
+	ChatID                        int64           `json:"chat_id"`
+	UserID                        int64           `json:"user_id"`
+	Permissions                   ChatPermissions `json:"permissions"`
+	UseIndependentChatPermissions bool            `json:"use_independent_chat_permissions,omitempty"`
+	UntilDate                     int             `json:"until_date,omitempty"`
+}
+
+// RestrictChatMember restricts a user in a chat.
+// Returns True on success.
+// See https://core.telegram.org/bots/api#restrictchatmember
+func (api *API) RestrictChatMember(params RestrictChatMemberP) (bool, error) {
+	req := NewRequestWithChatID[bool]("restrictChatMember", params, params.ChatID)
+	return req.Do(api)
+}
+
+// RestrictChatMemberWithContext is the context-aware variant of RestrictChatMember.
+// It executes the same request but uses ctx for cancellation and deadlines.
+// See https://core.telegram.org/bots/api#restrictchatmember
+func (api *API) RestrictChatMemberWithContext(ctx context.Context, params RestrictChatMemberP) (bool, error) {
+	req := NewRequestWithChatID[bool]("restrictChatMember", params, params.ChatID)
+	return req.DoWithContext(ctx, api)
+}
+
+// PromoteChatMember holds parameters for the promoteChatMember method.
+// See https://core.telegram.org/bots/api#promotechatmember
+type PromoteChatMember struct {
+	ChatID      int64 `json:"chat_id"`
+	UserID      int64 `json:"user_id"`
+	IsAnonymous bool  `json:"is_anonymous,omitempty"`
+
+	CanManageChat           bool `json:"can_manage_chat,omitempty"`
+	CanDeleteMessages       bool `json:"can_delete_messages,omitempty"`
+	CanManageVideoChats     bool `json:"can_manage_video_chats,omitempty"`
+	CanRestrictMembers      bool `json:"can_restrict_members,omitempty"`
+	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"`
+	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"`
+	CanManageTags           bool `json:"can_manage_tags,omitempty"`
+}
+
+// PromoteChatMember promotes or demotes a user in a chat.
+// Returns True on success.
+// See https://core.telegram.org/bots/api#promotechatmember
+func (api *API) PromoteChatMember(params PromoteChatMember) (bool, error) {
+	req := NewRequestWithChatID[bool]("promoteChatMember", params, params.ChatID)
+	return req.Do(api)
+}
+
+// PromoteChatMemberWithContext is the context-aware variant of PromoteChatMember.
+// It executes the same request but uses ctx for cancellation and deadlines.
+// See https://core.telegram.org/bots/api#promotechatmember
+func (api *API) PromoteChatMemberWithContext(ctx context.Context, params PromoteChatMember) (bool, error) {
+	req := NewRequestWithChatID[bool]("promoteChatMember", params, params.ChatID)
+	return req.DoWithContext(ctx, api)
+}
+
+// SetChatAdministratorCustomTitleP holds parameters for the setChatAdministratorCustomTitle method.
+// See https://core.telegram.org/bots/api#setchatadministratorcustomtitle
+type SetChatAdministratorCustomTitleP struct {
+	ChatID      int64  `json:"chat_id"`
+	UserID      int64  `json:"user_id"`
+	CustomTitle string `json:"custom_title"`
+}
+
+// SetChatAdministratorCustomTitle sets a custom title for an administrator.
+// Returns True on success.
+// See https://core.telegram.org/bots/api#setchatadministratorcustomtitle
+func (api *API) SetChatAdministratorCustomTitle(params SetChatAdministratorCustomTitleP) (bool, error) {
+	req := NewRequestWithChatID[bool]("setChatAdministratorCustomTitle", params, params.ChatID)
+	return req.Do(api)
+}
+
+// SetChatAdministratorCustomTitleWithContext is the context-aware variant of SetChatAdministratorCustomTitle.
+// It executes the same request but uses ctx for cancellation and deadlines.
+// See https://core.telegram.org/bots/api#setchatadministratorcustomtitle
+func (api *API) SetChatAdministratorCustomTitleWithContext(ctx context.Context, params SetChatAdministratorCustomTitleP) (bool, error) {
+	req := NewRequestWithChatID[bool]("setChatAdministratorCustomTitle", params, params.ChatID)
+	return req.DoWithContext(ctx, api)
+}
+
+// SetChatMemberTagP holds parameters for the setChatMemberTag method.
+// See https://core.telegram.org/bots/api#setchatmembertag
+type SetChatMemberTagP struct {
+	ChatID int64  `json:"chat_id"`
+	UserID int64  `json:"user_id"`
+	Tag    string `json:"tag,omitempty"`
+}
+
+// SetChatMemberTag sets a tag for a chat member.
+// Returns True on success.
+// See https://core.telegram.org/bots/api#setchatmembertag
+func (api *API) SetChatMemberTag(params SetChatMemberTagP) (bool, error) {
+	req := NewRequestWithChatID[bool]("setChatMemberTag", params, params.ChatID)
+	return req.Do(api)
+}
+
+// SetChatMemberTagWithContext is the context-aware variant of SetChatMemberTag.
+// It executes the same request but uses ctx for cancellation and deadlines.
+// See https://core.telegram.org/bots/api#setchatmembertag
+func (api *API) SetChatMemberTagWithContext(ctx context.Context, params SetChatMemberTagP) (bool, error) {
+	req := NewRequestWithChatID[bool]("setChatMemberTag", params, params.ChatID)
+	return req.DoWithContext(ctx, api)
+}
+
+// BanChatSenderChatP holds parameters for the banChatSenderChat method.
+// See https://core.telegram.org/bots/api#banchatsenderchat
+type BanChatSenderChatP struct {
+	ChatID       int64 `json:"chat_id"`
+	SenderChatID int64 `json:"sender_chat_id"`
+}
+
+// BanChatSenderChat bans a channel chat in a supergroup or channel.
+// Returns True on success.
+// See https://core.telegram.org/bots/api#banchatsenderchat
+func (api *API) BanChatSenderChat(params BanChatSenderChatP) (bool, error) {
+	req := NewRequestWithChatID[bool]("banChatSenderChat", params, params.ChatID)
+	return req.Do(api)
+}
+
+// BanChatSenderChatWithContext is the context-aware variant of BanChatSenderChat.
+// It executes the same request but uses ctx for cancellation and deadlines.
+// See https://core.telegram.org/bots/api#banchatsenderchat
+func (api *API) BanChatSenderChatWithContext(ctx context.Context, params BanChatSenderChatP) (bool, error) {
+	req := NewRequestWithChatID[bool]("banChatSenderChat", params, params.ChatID)
+	return req.DoWithContext(ctx, api)
+}
+
+// UnbanChatSenderChatP holds parameters for the unbanChatSenderChat method.
+// See https://core.telegram.org/bots/api#unbanchatsenderchat
+type UnbanChatSenderChatP struct {
+	ChatID       int64 `json:"chat_id"`
+	SenderChatID int64 `json:"sender_chat_id"`
+}
+
+// UnbanChatSenderChat unbans a previously banned channel chat.
+// Returns True on success.
+// See https://core.telegram.org/bots/api#unbanchatsenderchat
+func (api *API) UnbanChatSenderChat(params UnbanChatSenderChatP) (bool, error) {
+	req := NewRequestWithChatID[bool]("unbanChatSenderChat", params, params.ChatID)
+	return req.Do(api)
+}
+
+// UnbanChatSenderChatWithContext is the context-aware variant of UnbanChatSenderChat.
+// It executes the same request but uses ctx for cancellation and deadlines.
+// See https://core.telegram.org/bots/api#unbanchatsenderchat
+func (api *API) UnbanChatSenderChatWithContext(ctx context.Context, params UnbanChatSenderChatP) (bool, error) {
+	req := NewRequestWithChatID[bool]("unbanChatSenderChat", params, params.ChatID)
+	return req.DoWithContext(ctx, api)
+}
+
+// SetChatPermissionsP holds parameters for the setChatPermissions method.
+// See https://core.telegram.org/bots/api#setchatpermissions
+type SetChatPermissionsP struct {
+	ChatID                        int64           `json:"chat_id"`
+	Permissions                   ChatPermissions `json:"permissions"`
+	UseIndependentChatPermissions bool            `json:"use_independent_chat_permissions,omitempty"`
+}
+
+// SetChatPermissions sets default chat permissions for all members.
+// Returns True on success.
+// See https://core.telegram.org/bots/api#setchatpermissions
+func (api *API) SetChatPermissions(params SetChatPermissionsP) (bool, error) {
+	req := NewRequestWithChatID[bool]("setChatPermissions", params, params.ChatID)
+	return req.Do(api)
+}
+
+// SetChatPermissionsWithContext is the context-aware variant of SetChatPermissions.
+// It executes the same request but uses ctx for cancellation and deadlines.
+// See https://core.telegram.org/bots/api#setchatpermissions
+func (api *API) SetChatPermissionsWithContext(ctx context.Context, params SetChatPermissionsP) (bool, error) {
+	req := NewRequestWithChatID[bool]("setChatPermissions", params, params.ChatID)
+	return req.DoWithContext(ctx, api)
+}
+
+// ExportChatInviteLinkP holds parameters for the exportChatInviteLink method.
+// See https://core.telegram.org/bots/api#exportchatinvitelink
+type ExportChatInviteLinkP struct {
+	ChatID int64 `json:"chat_id"`
+}
+
+// ExportChatInviteLink generates a new primary invite link for a chat.
+// Returns the new invite link as string.
+// See https://core.telegram.org/bots/api#exportchatinvitelink
+func (api *API) ExportChatInviteLink(params ExportChatInviteLinkP) (string, error) {
+	req := NewRequestWithChatID[string]("exportChatInviteLink", params, params.ChatID)
+	return req.Do(api)
+}
+
+// ExportChatInviteLinkWithContext is the context-aware variant of ExportChatInviteLink.
+// It executes the same request but uses ctx for cancellation and deadlines.
+// See https://core.telegram.org/bots/api#exportchatinvitelink
+func (api *API) ExportChatInviteLinkWithContext(ctx context.Context, params ExportChatInviteLinkP) (string, error) {
+	req := NewRequestWithChatID[string]("exportChatInviteLink", params, params.ChatID)
+	return req.DoWithContext(ctx, api)
+}
+
+// CreateChatInviteLinkP holds parameters for the createChatInviteLink method.
+// See https://core.telegram.org/bots/api#createchatinvitelink
+type CreateChatInviteLinkP struct {
+	ChatID             int64   `json:"chat_id"`
+	Name               *string `json:"name,omitempty"`
+	ExpireDate         int     `json:"expire_date,omitempty"`
+	MemberLimit        int     `json:"member_limit,omitempty"`
+	CreatesJoinRequest bool    `json:"creates_join_request,omitempty"`
+}
+
+// CreateChatInviteLink creates an additional invite link for a chat.
+// Returns the created invite link.
+// See https://core.telegram.org/bots/api#createchatinvitelink
+func (api *API) CreateChatInviteLink(params CreateChatInviteLinkP) (ChatInviteLink, error) {
+	req := NewRequestWithChatID[ChatInviteLink]("createChatInviteLink", params, params.ChatID)
+	return req.Do(api)
+}
+
+// CreateChatInviteLinkWithContext is the context-aware variant of CreateChatInviteLink.
+// It executes the same request but uses ctx for cancellation and deadlines.
+// See https://core.telegram.org/bots/api#createchatinvitelink
+func (api *API) CreateChatInviteLinkWithContext(ctx context.Context, params CreateChatInviteLinkP) (ChatInviteLink, error) {
+	req := NewRequestWithChatID[ChatInviteLink]("createChatInviteLink", params, params.ChatID)
+	return req.DoWithContext(ctx, api)
+}
+
+// EditChatInviteLinkP holds parameters for the editChatInviteLink method.
+// See https://core.telegram.org/bots/api#editchatinvitelink
+type EditChatInviteLinkP struct {
+	ChatID     int64  `json:"chat_id"`
+	InviteLink string `json:"invite_link"`
+
+	Name               string `json:"name,omitempty"`
+	ExpireDate         int    `json:"expire_date,omitempty"`
+	MemberLimit        int    `json:"member_limit,omitempty"`
+	CreatesJoinRequest bool   `json:"creates_join_request,omitempty"`
+}
+
+// EditChatInviteLink edits a non‑primary invite link.
+// Returns the edited invite link.
+// See https://core.telegram.org/bots/api#editchatinvitelink
+func (api *API) EditChatInviteLink(params EditChatInviteLinkP) (ChatInviteLink, error) {
+	req := NewRequestWithChatID[ChatInviteLink]("editChatInviteLink", params, params.ChatID)
+	return req.Do(api)
+}
+
+// EditChatInviteLinkWithContext is the context-aware variant of EditChatInviteLink.
+// It executes the same request but uses ctx for cancellation and deadlines.
+// See https://core.telegram.org/bots/api#editchatinvitelink
+func (api *API) EditChatInviteLinkWithContext(ctx context.Context, params EditChatInviteLinkP) (ChatInviteLink, error) {
+	req := NewRequestWithChatID[ChatInviteLink]("editChatInviteLink", params, params.ChatID)
+	return req.DoWithContext(ctx, api)
+}
+
+// CreateChatSubscriptionInviteLinkP holds parameters for the createChatSubscriptionInviteLink method.
+// See https://core.telegram.org/bots/api#createchatsubscriptioninvitelink
+type CreateChatSubscriptionInviteLinkP struct {
+	ChatID             int64  `json:"chat_id"`
+	Name               string `json:"name,omitempty"`
+	SubscriptionPeriod int    `json:"subscription_period,omitempty"`
+	SubscriptionPrice  int    `json:"subscription_price,omitempty"`
+}
+
+// CreateChatSubscriptionInviteLink creates a subscription invite link for a channel chat.
+// Returns the created invite link.
+// See https://core.telegram.org/bots/api#createchatsubscriptioninvitelink
+func (api *API) CreateChatSubscriptionInviteLink(params CreateChatSubscriptionInviteLinkP) (ChatInviteLink, error) {
+	req := NewRequestWithChatID[ChatInviteLink]("createChatSubscriptionInviteLink", params, params.ChatID)
+	return req.Do(api)
+}
+
+// CreateChatSubscriptionInviteLinkWithContext is the context-aware variant of CreateChatSubscriptionInviteLink.
+// It executes the same request but uses ctx for cancellation and deadlines.
+// See https://core.telegram.org/bots/api#createchatsubscriptioninvitelink
+func (api *API) CreateChatSubscriptionInviteLinkWithContext(ctx context.Context, params CreateChatSubscriptionInviteLinkP) (ChatInviteLink, error) {
+	req := NewRequestWithChatID[ChatInviteLink]("createChatSubscriptionInviteLink", params, params.ChatID)
+	return req.DoWithContext(ctx, api)
+}
+
+// EditChatSubscriptionInviteLinkP holds parameters for the editChatSubscriptionInviteLink method.
+// See https://core.telegram.org/bots/api#editchatsubscriptioninvitelink
+type EditChatSubscriptionInviteLinkP struct {
+	ChatID     int64  `json:"chat_id"`
+	InviteLink string `json:"invite_link"`
+	Name       string `json:"name,omitempty"`
+}
+
+// EditChatSubscriptionInviteLink edits a subscription invite link.
+// Returns the edited invite link.
+// See https://core.telegram.org/bots/api#editchatsubscriptioninvitelink
+func (api *API) EditChatSubscriptionInviteLink(params EditChatSubscriptionInviteLinkP) (ChatInviteLink, error) {
+	req := NewRequestWithChatID[ChatInviteLink]("editChatSubscriptionInviteLink", params, params.ChatID)
+	return req.Do(api)
+}
+
+// EditChatSubscriptionInviteLinkWithContext is the context-aware variant of EditChatSubscriptionInviteLink.
+// It executes the same request but uses ctx for cancellation and deadlines.
+// See https://core.telegram.org/bots/api#editchatsubscriptioninvitelink
+func (api *API) EditChatSubscriptionInviteLinkWithContext(ctx context.Context, params EditChatSubscriptionInviteLinkP) (ChatInviteLink, error) {
+	req := NewRequestWithChatID[ChatInviteLink]("editChatSubscriptionInviteLink", params, params.ChatID)
+	return req.DoWithContext(ctx, api)
+}
+
+// RevokeChatInviteLinkP holds parameters for the revokeChatInviteLink method.
+// See https://core.telegram.org/bots/api#revokechatinvitelink
+type RevokeChatInviteLinkP struct {
+	ChatID     int64  `json:"chat_id"`
+	InviteLink string `json:"invite_link"`
+}
+
+// RevokeChatInviteLink revokes an invite link.
+// Returns the revoked invite link object.
+// See https://core.telegram.org/bots/api#revokechatinvitelink
+func (api *API) RevokeChatInviteLink(params RevokeChatInviteLinkP) (ChatInviteLink, error) {
+	req := NewRequestWithChatID[ChatInviteLink]("revokeChatInviteLink", params, params.ChatID)
+	return req.Do(api)
+}
+
+// RevokeChatInviteLinkWithContext is the context-aware variant of RevokeChatInviteLink.
+// It executes the same request but uses ctx for cancellation and deadlines.
+// See https://core.telegram.org/bots/api#revokechatinvitelink
+func (api *API) RevokeChatInviteLinkWithContext(ctx context.Context, params RevokeChatInviteLinkP) (ChatInviteLink, error) {
+	req := NewRequestWithChatID[ChatInviteLink]("revokeChatInviteLink", params, params.ChatID)
+	return req.DoWithContext(ctx, api)
+}
+
+// ApproveChatJoinRequestP holds parameters for the approveChatJoinRequest method.
+// See https://core.telegram.org/bots/api#approvechatjoinrequest
+type ApproveChatJoinRequestP struct {
+	ChatID int64 `json:"chat_id"`
+	UserID int64 `json:"user_id"`
+}
+
+// ApproveChatJoinRequest approves a chat join request.
+// Returns True on success.
+// See https://core.telegram.org/bots/api#approvechatjoinrequest
+func (api *API) ApproveChatJoinRequest(params ApproveChatJoinRequestP) (bool, error) {
+	req := NewRequestWithChatID[bool]("approveChatJoinRequest", params, params.ChatID)
+	return req.Do(api)
+}
+
+// ApproveChatJoinRequestWithContext is the context-aware variant of ApproveChatJoinRequest.
+// It executes the same request but uses ctx for cancellation and deadlines.
+// See https://core.telegram.org/bots/api#approvechatjoinrequest
+func (api *API) ApproveChatJoinRequestWithContext(ctx context.Context, params ApproveChatJoinRequestP) (bool, error) {
+	req := NewRequestWithChatID[bool]("approveChatJoinRequest", params, params.ChatID)
+	return req.DoWithContext(ctx, api)
+}
+
+// DeclineChatJoinRequestP holds parameters for the declineChatJoinRequest method.
+// See https://core.telegram.org/bots/api#declinechatjoinrequest
+type DeclineChatJoinRequestP struct {
+	ChatID int64 `json:"chat_id"`
+	UserID int64 `json:"user_id"`
+}
+
+// DeclineChatJoinRequest declines a chat join request.
+// Returns True on success.
+// See https://core.telegram.org/bots/api#declinechatjoinrequest
+func (api *API) DeclineChatJoinRequest(params DeclineChatJoinRequestP) (bool, error) {
+	req := NewRequestWithChatID[bool]("declineChatJoinRequest", params, params.ChatID)
+	return req.Do(api)
+}
+
+// DeclineChatJoinRequestWithContext is the context-aware variant of DeclineChatJoinRequest.
+// It executes the same request but uses ctx for cancellation and deadlines.
+// See https://core.telegram.org/bots/api#declinechatjoinrequest
+func (api *API) DeclineChatJoinRequestWithContext(ctx context.Context, params DeclineChatJoinRequestP) (bool, error) {
+	req := NewRequestWithChatID[bool]("declineChatJoinRequest", params, params.ChatID)
+	return req.DoWithContext(ctx, api)
+}
+
+// SetChatPhotoP holds parameters for the setChatPhoto method.
+// See https://core.telegram.org/bots/api#setchatphoto
+type SetChatPhotoP struct {
+	ChatID int64 `json:"chat_id"`
+}
+
+// SetChatPhoto changes the chat photo.
+// photo is the file to upload as the new photo.
+// Returns True on success.
+// See https://core.telegram.org/bots/api#setchatphoto
+func (api *API) SetChatPhoto(params SetChatPhotoP, photo UploaderFile) (bool, error) {
+	uploader := NewUploader(api)
+	defer func() {
+		_ = uploader.Close()
+	}()
+	req := NewUploaderRequestWithChatID[bool]("setChatPhoto", params, params.ChatID, photo.SetType(UploaderPhotoType))
+	return req.Do(uploader)
+}
+
+// DeleteChatPhotoP holds parameters for the deleteChatPhoto method.
+// See https://core.telegram.org/bots/api#deletechatphoto
+type DeleteChatPhotoP struct {
+	ChatID int64 `json:"chat_id"`
+}
+
+// DeleteChatPhoto deletes a chat photo.
+// Returns True on success.
+// See https://core.telegram.org/bots/api#deletechatphoto
+func (api *API) DeleteChatPhoto(params DeleteChatPhotoP) (bool, error) {
+	req := NewRequestWithChatID[bool]("deleteChatPhoto", params, params.ChatID)
+	return req.Do(api)
+}
+
+// DeleteChatPhotoWithContext is the context-aware variant of DeleteChatPhoto.
+// It executes the same request but uses ctx for cancellation and deadlines.
+// See https://core.telegram.org/bots/api#deletechatphoto
+func (api *API) DeleteChatPhotoWithContext(ctx context.Context, params DeleteChatPhotoP) (bool, error) {
+	req := NewRequestWithChatID[bool]("deleteChatPhoto", params, params.ChatID)
+	return req.DoWithContext(ctx, api)
+}
+
+// SetChatTitleP holds parameters for the setChatTitle method.
+// See https://core.telegram.org/bots/api#setchattitle
+type SetChatTitleP struct {
+	ChatID int64  `json:"chat_id"`
+	Title  string `json:"title"`
+}
+
+// SetChatTitle changes the chat title.
+// Returns True on success.
+// See https://core.telegram.org/bots/api#setchattitle
+func (api *API) SetChatTitle(params SetChatTitleP) (bool, error) {
+	req := NewRequestWithChatID[bool]("setChatTitle", params, params.ChatID)
+	return req.Do(api)
+}
+
+// SetChatTitleWithContext is the context-aware variant of SetChatTitle.
+// It executes the same request but uses ctx for cancellation and deadlines.
+// See https://core.telegram.org/bots/api#setchattitle
+func (api *API) SetChatTitleWithContext(ctx context.Context, params SetChatTitleP) (bool, error) {
+	req := NewRequestWithChatID[bool]("setChatTitle", params, params.ChatID)
+	return req.DoWithContext(ctx, api)
+}
+
+// SetChatDescriptionP holds parameters for the setChatDescription method.
+// See https://core.telegram.org/bots/api#setchatdescription
+type SetChatDescriptionP struct {
+	ChatID      int64  `json:"chat_id"`
+	Description string `json:"description"`
+}
+
+// SetChatDescription changes the chat description.
+// Returns True on success.
+// See https://core.telegram.org/bots/api#setchatdescription
+func (api *API) SetChatDescription(params SetChatDescriptionP) (bool, error) {
+	req := NewRequestWithChatID[bool]("setChatDescription", params, params.ChatID)
+	return req.Do(api)
+}
+
+// SetChatDescriptionWithContext is the context-aware variant of SetChatDescription.
+// It executes the same request but uses ctx for cancellation and deadlines.
+// See https://core.telegram.org/bots/api#setchatdescription
+func (api *API) SetChatDescriptionWithContext(ctx context.Context, params SetChatDescriptionP) (bool, error) {
+	req := NewRequestWithChatID[bool]("setChatDescription", params, params.ChatID)
+	return req.DoWithContext(ctx, api)
+}
+
+// PinChatMessageP holds parameters for the pinChatMessage method.
+// See https://core.telegram.org/bots/api#pinchatmessage
+type PinChatMessageP struct {
+	BusinessConnectionID *string `json:"business_connection_id,omitempty"`
+	ChatID               int64   `json:"chat_id"`
+	MessageID            int     `json:"message_id"`
+	DisableNotification  bool    `json:"disable_notification,omitempty"`
+}
+
+// PinChatMessage pins a message in a chat.
+// Returns True on success.
+// See https://core.telegram.org/bots/api#pinchatmessage
+func (api *API) PinChatMessage(params PinChatMessageP) (bool, error) {
+	req := NewRequestWithChatID[bool]("pinChatMessage", params, params.ChatID)
+	return req.Do(api)
+}
+
+// PinChatMessageWithContext is the context-aware variant of PinChatMessage.
+// It executes the same request but uses ctx for cancellation and deadlines.
+// See https://core.telegram.org/bots/api#pinchatmessage
+func (api *API) PinChatMessageWithContext(ctx context.Context, params PinChatMessageP) (bool, error) {
+	req := NewRequestWithChatID[bool]("pinChatMessage", params, params.ChatID)
+	return req.DoWithContext(ctx, api)
+}
+
+// UnpinChatMessageP holds parameters for the unpinChatMessage method.
+// See https://core.telegram.org/bots/api#unpinchatmessage
+type UnpinChatMessageP struct {
+	BusinessConnectionID *string `json:"business_connection_id,omitempty"`
+	ChatID               int64   `json:"chat_id"`
+	MessageID            int     `json:"message_id"`
+}
+
+// UnpinChatMessage unpins a message in a chat.
+// Returns True on success.
+// See https://core.telegram.org/bots/api#unpinchatmessage
+func (api *API) UnpinChatMessage(params UnpinChatMessageP) (bool, error) {
+	req := NewRequestWithChatID[bool]("unpinChatMessage", params, params.ChatID)
+	return req.Do(api)
+}
+
+// UnpinChatMessageWithContext is the context-aware variant of UnpinChatMessage.
+// It executes the same request but uses ctx for cancellation and deadlines.
+// See https://core.telegram.org/bots/api#unpinchatmessage
+func (api *API) UnpinChatMessageWithContext(ctx context.Context, params UnpinChatMessageP) (bool, error) {
+	req := NewRequestWithChatID[bool]("unpinChatMessage", params, params.ChatID)
+	return req.DoWithContext(ctx, api)
+}
+
+// UnpinAllChatMessagesP holds parameters for the unpinAllChatMessages method.
+// See https://core.telegram.org/bots/api#unpinallchatmessages
+type UnpinAllChatMessagesP struct {
+	ChatID int64 `json:"chat_id"`
+}
+
+// UnpinAllChatMessages unpins all pinned messages in a chat.
+// Returns True on success.
+// See https://core.telegram.org/bots/api#unpinallchatmessages
+func (api *API) UnpinAllChatMessages(params UnpinAllChatMessagesP) (bool, error) {
+	req := NewRequestWithChatID[bool]("unpinAllChatMessages", params, params.ChatID)
+	return req.Do(api)
+}
+
+// UnpinAllChatMessagesWithContext is the context-aware variant of UnpinAllChatMessages.
+// It executes the same request but uses ctx for cancellation and deadlines.
+// See https://core.telegram.org/bots/api#unpinallchatmessages
+func (api *API) UnpinAllChatMessagesWithContext(ctx context.Context, params UnpinAllChatMessagesP) (bool, error) {
+	req := NewRequestWithChatID[bool]("unpinAllChatMessages", params, params.ChatID)
+	return req.DoWithContext(ctx, api)
+}
+
+// LeaveChatP holds parameters for the leaveChat method.
+// See https://core.telegram.org/bots/api#leavechat
+type LeaveChatP struct {
+	ChatID int64 `json:"chat_id"`
+}
+
+// LeaveChat makes the bot leave a chat.
+// Returns True on success.
+// See https://core.telegram.org/bots/api#leavechat
+func (api *API) LeaveChat(params LeaveChatP) (bool, error) {
+	req := NewRequestWithChatID[bool]("leaveChat", params, params.ChatID) // fixed method name
+	return req.Do(api)
+}
+
+// LeaveChatWithContext is the context-aware variant of LeaveChat.
+// It executes the same request but uses ctx for cancellation and deadlines.
+// See https://core.telegram.org/bots/api#leavechat
+func (api *API) LeaveChatWithContext(ctx context.Context, params LeaveChatP) (bool, error) {
+	req := NewRequestWithChatID[bool]("leaveChat", params, params.ChatID) // fixed method name
+	return req.DoWithContext(ctx, api)
+}
+
+// GetChatP holds parameters for the getChat method.
+// See https://core.telegram.org/bots/api#getchat
+type GetChatP struct {
+	ChatID int64 `json:"chat_id"`
+}
+
+// GetChat gets up‑to‑date information about a chat.
+// See https://core.telegram.org/bots/api#getchat
+func (api *API) GetChat(params GetChatP) (ChatFullInfo, error) {
+	req := NewRequestWithChatID[ChatFullInfo]("getChat", params, params.ChatID) // fixed method name
+	return req.Do(api)
+}
+
+// GetChatWithContext is the context-aware variant of GetChat.
+// It executes the same request but uses ctx for cancellation and deadlines.
+// See https://core.telegram.org/bots/api#getchat
+func (api *API) GetChatWithContext(ctx context.Context, params GetChatP) (ChatFullInfo, error) {
+	req := NewRequestWithChatID[ChatFullInfo]("getChat", params, params.ChatID) // fixed method name
+	return req.DoWithContext(ctx, api)
+}
+
+// GetChatAdministratorsP holds parameters for the getChatAdministrators method.
+// See https://core.telegram.org/bots/api#getchatadministrators
+type GetChatAdministratorsP struct {
+	ChatID int64 `json:"chat_id"`
+}
+
+// GetChatAdministrators returns a list of administrators in a chat.
+// See https://core.telegram.org/bots/api#getchatadministrators
+func (api *API) GetChatAdministrators(params GetChatAdministratorsP) ([]ChatMember, error) {
+	req := NewRequestWithChatID[[]ChatMember]("getChatAdministrators", params, params.ChatID)
+	return req.Do(api)
+}
+
+// GetChatAdministratorsWithContext is the context-aware variant of GetChatAdministrators.
+// It executes the same request but uses ctx for cancellation and deadlines.
+// See https://core.telegram.org/bots/api#getchatadministrators
+func (api *API) GetChatAdministratorsWithContext(ctx context.Context, params GetChatAdministratorsP) ([]ChatMember, error) {
+	req := NewRequestWithChatID[[]ChatMember]("getChatAdministrators", params, params.ChatID)
+	return req.DoWithContext(ctx, api)
+}
+
+// GetChatMembersCountP holds parameters for the getChatMemberCount method.
+// See https://core.telegram.org/bots/api#getchatmembercount
+type GetChatMembersCountP struct {
+	ChatID int64 `json:"chat_id"`
+}
+
+// GetChatMemberCount returns the number of members in a chat.
+// See https://core.telegram.org/bots/api#getchatmembercount
+func (api *API) GetChatMemberCount(params GetChatMembersCountP) (int, error) {
+	req := NewRequestWithChatID[int]("getChatMemberCount", params, params.ChatID)
+	return req.Do(api)
+}
+
+// GetChatMemberCountWithContext is the context-aware variant of GetChatMemberCount.
+// It executes the same request but uses ctx for cancellation and deadlines.
+// See https://core.telegram.org/bots/api#getchatmembercount
+func (api *API) GetChatMemberCountWithContext(ctx context.Context, params GetChatMembersCountP) (int, error) {
+	req := NewRequestWithChatID[int]("getChatMemberCount", params, params.ChatID)
+	return req.DoWithContext(ctx, api)
+}
+
+// GetChatMemberP holds parameters for the getChatMember method.
+// See https://core.telegram.org/bots/api#getchatmember
+type GetChatMemberP struct {
+	ChatID int64 `json:"chat_id"`
+	UserID int64 `json:"user_id"`
+}
+
+// GetChatMember returns information about a member of a chat.
+// See https://core.telegram.org/bots/api#getchatmember
+func (api *API) GetChatMember(params GetChatMemberP) (ChatMember, error) {
+	req := NewRequestWithChatID[ChatMember]("getChatMember", params, params.ChatID)
+	return req.Do(api)
+}
+
+// GetChatMemberWithContext is the context-aware variant of GetChatMember.
+// It executes the same request but uses ctx for cancellation and deadlines.
+// See https://core.telegram.org/bots/api#getchatmember
+func (api *API) GetChatMemberWithContext(ctx context.Context, params GetChatMemberP) (ChatMember, error) {
+	req := NewRequestWithChatID[ChatMember]("getChatMember", params, params.ChatID)
+	return req.DoWithContext(ctx, api)
+}
+
+// SetChatStickerSetP holds parameters for the setChatStickerSet method.
+// See https://core.telegram.org/bots/api#setchatstickerset
+type SetChatStickerSetP struct {
+	ChatID         int64  `json:"chat_id"`
+	StickerSetName string `json:"sticker_set_name"`
+}
+
+// SetChatStickerSet associates a sticker set with a supergroup.
+// Returns True on success.
+// See https://core.telegram.org/bots/api#setchatstickerset
+func (api *API) SetChatStickerSet(params SetChatStickerSetP) (bool, error) {
+	req := NewRequestWithChatID[bool]("setChatStickerSet", params, params.ChatID)
+	return req.Do(api)
+}
+
+// SetChatStickerSetWithContext is the context-aware variant of SetChatStickerSet.
+// It executes the same request but uses ctx for cancellation and deadlines.
+// See https://core.telegram.org/bots/api#setchatstickerset
+func (api *API) SetChatStickerSetWithContext(ctx context.Context, params SetChatStickerSetP) (bool, error) {
+	req := NewRequestWithChatID[bool]("setChatStickerSet", params, params.ChatID)
+	return req.DoWithContext(ctx, api)
+}
+
+// DeleteChatStickerSetP holds parameters for the deleteChatStickerSet method.
+// See https://core.telegram.org/bots/api#deletechatstickerset
+type DeleteChatStickerSetP struct {
+	ChatID int64 `json:"chat_id"`
+}
+
+// DeleteChatStickerSet deletes a sticker set from a supergroup.
+// Returns True on success.
+// See https://core.telegram.org/bots/api#deletechatstickerset
+func (api *API) DeleteChatStickerSet(params DeleteChatStickerSetP) (bool, error) {
+	req := NewRequestWithChatID[bool]("deleteChatStickerSet", params, params.ChatID)
+	return req.Do(api)
+}
+
+// DeleteChatStickerSetWithContext is the context-aware variant of DeleteChatStickerSet.
+// It executes the same request but uses ctx for cancellation and deadlines.
+// See https://core.telegram.org/bots/api#deletechatstickerset
+func (api *API) DeleteChatStickerSetWithContext(ctx context.Context, params DeleteChatStickerSetP) (bool, error) {
+	req := NewRequestWithChatID[bool]("deleteChatStickerSet", params, params.ChatID)
+	return req.DoWithContext(ctx, api)
+}
+
+// GetUserChatBoostsP holds parameters for the getUserChatBoosts method.
+// See https://core.telegram.org/bots/api#getuserchatboosts
+type GetUserChatBoostsP struct {
+	ChatID int64 `json:"chat_id"`
+	UserID int64 `json:"user_id"`
+}
+
+// GetUserChatBoosts returns the list of boosts a user has given to a chat.
+// See https://core.telegram.org/bots/api#getuserchatboosts
+func (api *API) GetUserChatBoosts(params GetUserChatBoostsP) (UserChatBoosts, error) {
+	req := NewRequestWithChatID[UserChatBoosts]("getUserChatBoosts", params, params.ChatID)
+	return req.Do(api)
+}
+
+// GetUserChatBoostsWithContext is the context-aware variant of GetUserChatBoosts.
+// It executes the same request but uses ctx for cancellation and deadlines.
+// See https://core.telegram.org/bots/api#getuserchatboosts
+func (api *API) GetUserChatBoostsWithContext(ctx context.Context, params GetUserChatBoostsP) (UserChatBoosts, error) {
+	req := NewRequestWithChatID[UserChatBoosts]("getUserChatBoosts", params, params.ChatID)
+	return req.DoWithContext(ctx, api)
+}
+
+// GetChatGiftsP holds parameters for the getChatGifts method.
+// See https://core.telegram.org/bots/api#getchatgifts
+type GetChatGiftsP struct {
+	ChatID                      int64  `json:"chat_id"`
+	ExcludeUnsaved              bool   `json:"exclude_unsaved,omitempty"`
+	ExcludeSaved                bool   `json:"exclude_saved,omitempty"`
+	ExcludeUnlimited            bool   `json:"exclude_unlimited,omitempty"`
+	ExcludeLimitedUpgradable    bool   `json:"exclude_limited_upgradable,omitempty"`
+	ExcludeLimitedNonUpgradable bool   `json:"exclude_limited_non_upgradable,omitempty"`
+	ExcludeUnique               bool   `json:"exclude_unique,omitempty"`
+	ExcludeFromBlockchain       bool   `json:"exclude_from_blockchain,omitempty"`
+	SortByPrice                 bool   `json:"sort_by_price,omitempty"`
+	Offset                      string `json:"offset,omitempty"`
+	Limit                       int    `json:"limit,omitempty"`
+}
+
+// GetChatGifts returns gifts owned by a chat.
+// See https://core.telegram.org/bots/api#getchatgifts
+func (api *API) GetChatGifts(params GetChatGiftsP) (OwnedGifts, error) {
+	req := NewRequestWithChatID[OwnedGifts]("getChatGifts", params, params.ChatID)
+	return req.Do(api)
+}
+
+// GetChatGiftsWithContext is the context-aware variant of GetChatGifts.
+// It executes the same request but uses ctx for cancellation and deadlines.
+// See https://core.telegram.org/bots/api#getchatgifts
+func (api *API) GetChatGiftsWithContext(ctx context.Context, params GetChatGiftsP) (OwnedGifts, error) {
+	req := NewRequestWithChatID[OwnedGifts]("getChatGifts", params, params.ChatID)
+	return req.DoWithContext(ctx, api)
+}

tgapi/chat_types.go

@@ -0,0 +1,276 @@
+package tgapi
+
+// Chat represents a chat (private, group, supergroup, channel).
+// See https://core.telegram.org/bots/api#chat
+type Chat struct {
+	ID               int64   `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"`
+}
+
+// ChatType represents the type of a chat.
+type ChatType string
+
+const (
+	// 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 identifies a channel chat.
+	ChatTypeChannel ChatType = "channel"
+)
+
+// ChatFullInfo contains full information about a chat.
+// See https://core.telegram.org/bots/api#chatfullinfo
+type ChatFullInfo struct {
+	ID               int64      `json:"id"`
+	Type             ChatType   `json:"type"`
+	Title            string     `json:"title"`
+	Username         string     `json:"username"`
+	FirstName        string     `json:"first_name"`
+	LastName         string     `json:"last_name"`
+	IsForum          bool       `json:"is_forum"`
+	IsDirectMessages bool       `json:"is_direct_messages"`
+	AccentColorID    int        `json:"accent_color_id"`
+	MaxReactionCount int        `json:"max_reaction_count"`
+	Photo            *ChatPhoto `json:"photo,omitempty"`
+	ActiveUsernames  []string   `json:"active_usernames,omitempty"`
+	Birthdate        *Birthdate `json:"birthdate,omitempty"`
+
+	BusinessIntro        *BusinessIntro        `json:"business_intro,omitempty"`
+	BusinessLocation     *BusinessLocation     `json:"business_location,omitempty"`
+	BusinessOpeningHours *BusinessOpeningHours `json:"business_opening_hours,omitempty"`
+
+	PersonalChat *Chat `json:"personal_chat,omitempty"`
+	ParentChat   *Chat `json:"parent_chat,omitempty"`
+
+	AvailableReaction []ReactionType `json:"available_reaction,omitempty"`
+
+	BackgroundCustomEmojiID        *string `json:"background_custom_emoji_id,omitempty"`
+	ProfileAccentColorID           *int    `json:"profile_accent_color_id,omitempty"`
+	ProfileBackgroundCustomEmojiID *string `json:"profile_background_custom_emoji_id,omitempty"`
+	EmojiStatusCustomEmojiID       *string `json:"emoji_status_custom_emoji_id,omitempty"`
+	EmojiStatusExpirationDate      *int    `json:"emoji_status_expiration_date,omitempty"`
+
+	Bio                                *string `json:"bio,omitempty"`
+	HasPrivateForwards                 *bool   `json:"has_private_forwards,omitempty"`
+	HasRestrictedVoiceAndVideoMessages *bool   `json:"has_restricted_voice_and_video_messages,omitempty"`
+	JoinToSendMessages                 *bool   `json:"join_to_send_messages,omitempty"`
+	JoinByRequest                      *bool   `json:"join_by_request,omitempty"`
+
+	Description       *string            `json:"description,omitempty"`
+	InviteLink        *string            `json:"invite_link,omitempty"`
+	PinnedMessage     *Message           `json:"pinned_message,omitempty"`
+	Permissions       *ChatPermissions   `json:"permissions,omitempty"`
+	AcceptedGiftTypes *AcceptedGiftTypes `json:"accepted_gift_types,omitempty"`
+
+	CanSendPaidMedia             *bool   `json:"can_send_paid_media,omitempty"`
+	SlowModeDelay                *int    `json:"slow_mode_delay,omitempty"`
+	UnrestrictedBoostCount       *int    `json:"unrestricted_boost_count,omitempty"`
+	MessageAutoDeleteTime        *int    `json:"message_auto_delete_time,omitempty"`
+	HasAggressiveAntiSpamEnabled *bool   `json:"has_aggressive_anti_spam_enabled,omitempty"`
+	HasHiddenMembers             *bool   `json:"has_hidden_members,omitempty"`
+	HasProtectedContent          *bool   `json:"has_protected_content,omitempty"`
+	HasVisibleHistory            *bool   `json:"has_visible_history,omitempty"`
+	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                 *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"`
+}
+
+// ChatPhoto represents a chat photo.
+// See https://core.telegram.org/bots/api#chatphoto
+type ChatPhoto struct {
+	SmallFileID       string `json:"small_file_id"`
+	SmallFileUniqueID string `json:"small_file_unique_id"`
+	BigFileID         string `json:"big_file_id"`
+	BigFileUniqueID   string `json:"big_file_unique_id"`
+}
+
+// ChatPermissions describes actions that a non‑administrator user is allowed to take in a chat.
+// 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"`
+	CanSendPolls         bool `json:"can_send_polls"`
+	CanSendOtherMessages bool `json:"can_send_other_messages"`
+	CanAddWebPagePreview bool `json:"can_add_web_page_preview"`
+	CanEditTag           bool `json:"can_edit_tag"`
+	CanChangeInfo        bool `json:"can_change_info"`
+	CanInviteUsers       bool `json:"can_invite_users"`
+	CanPinMessages       bool `json:"can_pin_messages"`
+	CanManageTopics      bool `json:"can_manage_topics"`
+}
+
+// ChatLocation represents a location to which a chat is connected.
+// 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.
+// See https://core.telegram.org/bots/api#chatinvitelink
+type ChatInviteLink struct {
+	InviteLink        string `json:"invite_link"`
+	Creator           User   `json:"creator"`
+	CreateJoinRequest bool   `json:"creates_join_request"`
+	IsPrimary         bool   `json:"is_primary"`
+	IsRevoked         bool   `json:"is_revoked"`
+
+	Name                    *string `json:"name,omitempty"`
+	ExpireDate              *int    `json:"expire_date,omitempty"`
+	MemberLimit             *int    `json:"member_limit,omitempty"`
+	PendingJoinRequestCount *int    `json:"pending_join_request_count,omitempty"`
+	SubscriptionPeriod      *int    `json:"subscription_period,omitempty"`
+	SubscriptionPrice       *int    `json:"subscription_price,omitempty"`
+}
+
+// ChatMemberStatusType indicates the status of a chat member.
+type ChatMemberStatusType string
+
+const (
+	// ChatMemberStatusOwner identifies a chat owner.
+	ChatMemberStatusOwner ChatMemberStatusType = "owner"
+	// ChatMemberStatusAdministrator identifies a chat administrator.
+	ChatMemberStatusAdministrator ChatMemberStatusType = "administrator"
+	// 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.
+// See https://core.telegram.org/bots/api#chatmember
+type ChatMember struct {
+	Status ChatMemberStatusType `json:"status"`
+	User   User                 `json:"user"`
+	Tag    string               `json:"tag,omitempty"`
+
+	// Owner
+	IsAnonymous *bool   `json:"is_anonymous"`
+	CustomTitle *string `json:"custom_title,omitempty"`
+
+	// Administrator
+	CanBeEdited         *bool `json:"can_be_edited,omitempty"`
+	CanManageChat       *bool `json:"can_manage_chat,omitempty"`
+	CanDeleteMessages   *bool `json:"can_delete_messages,omitempty"`
+	CanManageVideoChats *bool `json:"can_manage_video_chats,omitempty"`
+	CanRestrictMembers  *bool `json:"can_restrict_members,omitempty"`
+	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"`
+
+	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"`
+	CanManageTags           *bool `json:"can_manage_tags,omitempty"`
+
+	// Member
+	UntilDate *int `json:"until_date,omitempty"`
+
+	// 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"`
+	CanSendPolls         *bool `json:"can_send_polls,omitempty"`
+	CanSendOtherMessages *bool `json:"can_send_other_messages,omitempty"`
+	CanAddWebPagePreview *bool `json:"can_add_web_page_preview,omitempty"`
+	CanEditTag           *bool `json:"can_edit_tag,omitempty"`
+}
+
+// ChatBoostSource describes the source of a chat boost.
+// See https://core.telegram.org/bots/api#chatboostsource
+type ChatBoostSource struct {
+	Source string `json:"source"`
+	User   User   `json:"user"`
+
+	// Giveaway
+	GiveawayMessageID *int  `json:"giveaway_message_id,omitempty"`
+	PrizeStarCount    *int  `json:"prize_star_count,omitempty"`
+	IsUnclaimed       *bool `json:"is_unclaimed,omitempty"`
+}
+
+// ChatBoost represents a boost added to a chat.
+// See https://core.telegram.org/bots/api#chatboost
+type ChatBoost struct {
+	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.
+// See https://core.telegram.org/bots/api#userchatboosts
+type UserChatBoosts struct {
+	Boosts []ChatBoost `json:"boosts"`
+}
+
+// ChatAdministratorRights represents the rights of an administrator in a chat.
+// See https://core.telegram.org/bots/api#chatadministratorrights
+type ChatAdministratorRights struct {
+	IsAnonymous         bool `json:"is_anonymous"`
+	CanManageChat       bool `json:"can_manage_chat"`
+	CanDeleteMessages   bool `json:"can_delete_messages"`
+	CanManageVideoChats bool `json:"can_manage_video_chats"`
+	CanRestrictMembers  bool `json:"can_restrict_members"`
+	CanPromoteMembers   bool `json:"can_promote_members"`
+	CanChangeInfo       bool `json:"can_change_info"`
+	CanInviteUsers      bool `json:"can_invite_users"`
+	CanPostStories      bool `json:"can_post_stories"`
+	CanEditStories      bool `json:"can_edit_stories"`
+	CanDeleteStories    bool `json:"can_delete_stories"`
+
+	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"`
+	CanManageTags           *bool `json:"can_manage_tags,omitempty"`
+}
+
+// ChatBoostUpdated represents a boost added to a chat or changed.
+// 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.
+// 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"`
+}

tgapi/errors.go

@@ -0,0 +1,15 @@
+package tgapi
+
+import "errors"
+
+// ErrRateLimit reports that a request exceeded the configured rate limiter.
+var ErrRateLimit = errors.New("rate limit exceeded")
+
+// ErrPoolUnexpected reports an unexpected result type returned from the worker pool.
+var ErrPoolUnexpected = errors.New("unexpected response from pool")
+
+// 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")

tgapi/forum_methods.go

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

tgapi/forum_types.go

@@ -0,0 +1,21 @@
+package tgapi
+
+// ForumTopic represents a forum topic.
+// See https://core.telegram.org/bots/api#forumtopic
+type ForumTopic struct {
+	MessageThreadID   int    `json:"message_thread_id"`
+	Name              string `json:"name"`
+	IconColor         int    `json:"icon_color"`
+	IconCustomEmojiID string `json:"icon_custom_emoji_id,omitempty"`
+	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.
+// 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
+)

tgapi/games_methods.go

@@ -0,0 +1,102 @@
+package tgapi
+
+import "context"
+
+// SendGameP holds parameters for the sendGame method.
+// See https://core.telegram.org/bots/api#sendgame
+type SendGameP 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.
+// See https://core.telegram.org/bots/api#sendgame
+func (api *API) SendGame(params SendGameP) (Message, error) {
+	req := NewRequestWithChatID[Message]("sendGame", params, params.ChatID)
+	return req.Do(api)
+}
+
+// SendGameWithContext is the context-aware variant of SendGame.
+// It executes the same request but uses ctx for cancellation and deadlines.
+// See https://core.telegram.org/bots/api#sendgame
+func (api *API) SendGameWithContext(ctx context.Context, params SendGameP) (Message, error) {
+	req := NewRequestWithChatID[Message]("sendGame", params, params.ChatID)
+	return req.DoWithContext(ctx, api)
+}
+
+// SetGameScoreP holds parameters for the setGameScore method.
+// See https://core.telegram.org/bots/api#setgamescore
+type SetGameScoreP 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.
+// If inline_message_id is provided, returns a boolean success flag.
+// Otherwise returns the edited Message.
+// See https://core.telegram.org/bots/api#setgamescore
+func (api *API) SetGameScore(params SetGameScoreP) (Message, bool, error) {
+	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.
+// It executes the same request but uses ctx for cancellation and deadlines.
+// See https://core.telegram.org/bots/api#setgamescore
+func (api *API) SetGameScoreWithContext(ctx context.Context, params SetGameScoreP) (Message, bool, error) {
+	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
+}
+
+// GetGameHighScoresP holds parameters for the getGameHighScores method.
+// See https://core.telegram.org/bots/api#getgamehighscores
+type GetGameHighScoresP 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.
+// See https://core.telegram.org/bots/api#getgamehighscores
+func (api *API) GetGameHighScores(params GetGameHighScoresP) ([]GameHighScore, error) {
+	req := NewRequestWithChatID[[]GameHighScore]("getGameHighScores", params, params.ChatID)
+	return req.Do(api)
+}
+
+// GetGameHighScoresWithContext is the context-aware variant of GetGameHighScores.
+// It executes the same request but uses ctx for cancellation and deadlines.
+// See https://core.telegram.org/bots/api#getgamehighscores
+func (api *API) GetGameHighScoresWithContext(ctx context.Context, params GetGameHighScoresP) ([]GameHighScore, error) {
+	req := NewRequestWithChatID[[]GameHighScore]("getGameHighScores", params, params.ChatID)
+	return req.DoWithContext(ctx, api)
+}

tgapi/games_types.go

@@ -0,0 +1,9 @@
+package tgapi
+
+// GameHighScore represents one row in a game high score table.
+// 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,78 @@
+package tgapi
+
+import "context"
+
+// AnswerInlineQueryP holds parameters for the answerInlineQuery method.
+// See https://core.telegram.org/bots/api#answerinlinequery
+type AnswerInlineQueryP 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.
+// Returns true on success.
+// See https://core.telegram.org/bots/api#answerinlinequery
+func (api *API) AnswerInlineQuery(params AnswerInlineQueryP) (bool, error) {
+	req := NewRequest[bool]("answerInlineQuery", params)
+	return req.Do(api)
+}
+
+// AnswerInlineQueryWithContext is the context-aware variant of AnswerInlineQuery.
+// It executes the same request but uses ctx for cancellation and deadlines.
+// See https://core.telegram.org/bots/api#answerinlinequery
+func (api *API) AnswerInlineQueryWithContext(ctx context.Context, params AnswerInlineQueryP) (bool, error) {
+	req := NewRequest[bool]("answerInlineQuery", params)
+	return req.DoWithContext(ctx, api)
+}
+
+// AnswerWebAppQueryP holds parameters for the answerWebAppQuery method.
+// See https://core.telegram.org/bots/api#answerwebappquery
+type AnswerWebAppQueryP struct {
+	WebAppQueryID string            `json:"web_app_query_id"`
+	Result        InlineQueryResult `json:"result"`
+}
+
+// AnswerWebAppQuery sets the result of a Web App interaction.
+// See https://core.telegram.org/bots/api#answerwebappquery
+func (api *API) AnswerWebAppQuery(params AnswerWebAppQueryP) (SentWebAppMessage, error) {
+	req := NewRequest[SentWebAppMessage]("answerWebAppQuery", params)
+	return req.Do(api)
+}
+
+// AnswerWebAppQueryWithContext is the context-aware variant of AnswerWebAppQuery.
+// It executes the same request but uses ctx for cancellation and deadlines.
+// See https://core.telegram.org/bots/api#answerwebappquery
+func (api *API) AnswerWebAppQueryWithContext(ctx context.Context, params AnswerWebAppQueryP) (SentWebAppMessage, error) {
+	req := NewRequest[SentWebAppMessage]("answerWebAppQuery", params)
+	return req.DoWithContext(ctx, api)
+}
+
+// SavePreparedInlineMessageP holds parameters for the savePreparedInlineMessage method.
+// See https://core.telegram.org/bots/api#savepreparedinlinemessage
+type SavePreparedInlineMessageP 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.
+// See https://core.telegram.org/bots/api#savepreparedinlinemessage
+func (api *API) SavePreparedInlineMessage(params SavePreparedInlineMessageP) (PreparedInlineMessage, error) {
+	req := NewRequest[PreparedInlineMessage]("savePreparedInlineMessage", params)
+	return req.Do(api)
+}
+
+// SavePreparedInlineMessageWithContext is the context-aware variant of SavePreparedInlineMessage.
+// It executes the same request but uses ctx for cancellation and deadlines.
+// See https://core.telegram.org/bots/api#savepreparedinlinemessage
+func (api *API) SavePreparedInlineMessageWithContext(ctx context.Context, params SavePreparedInlineMessageP) (PreparedInlineMessage, error) {
+	req := NewRequest[PreparedInlineMessage]("savePreparedInlineMessage", params)
+	return req.DoWithContext(ctx, api)
+}

tgapi/inline_types.go

@@ -0,0 +1,26 @@
+package tgapi
+
+// InlineQueryResult is a JSON-serializable inline query result object.
+// See https://core.telegram.org/bots/api#inlinequeryresult
+type InlineQueryResult map[string]any
+
+// InlineQueryResultsButton represents a button shown above inline query results.
+// 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"`
+}
+
+// SentWebAppMessage describes an inline message sent by a Web App on behalf of a user.
+// See https://core.telegram.org/bots/api#sentwebappmessage
+type SentWebAppMessage struct {
+	InlineMessageID string `json:"inline_message_id,omitempty"`
+}
+
+// PreparedInlineMessage describes a prepared inline message.
+// See https://core.telegram.org/bots/api#preparedinlinemessage
+type PreparedInlineMessage struct {
+	ID             string `json:"id"`
+	ExpirationDate int    `json:"expiration_date"`
+}

tgapi/messages_methods.go

@@ -0,0 +1,917 @@
+package tgapi
+
+import "context"
+
+// SendMessageP holds parameters for the sendMessage method.
+// See https://core.telegram.org/bots/api#sendmessage
+type SendMessageP struct {
+	BusinessConnectionID  string `json:"business_connection_id,omitempty"`
+	ChatID                int64  `json:"chat_id"`
+	MessageThreadID       int    `json:"message_thread_id,omitempty"`
+	DirectMessagesTopicID int64  `json:"direct_messages_topic_id,omitempty"`
+
+	Text                 string              `json:"text"`
+	ParseMode            ParseMode           `json:"parse_mode,omitempty"`
+	Entities             []MessageEntity     `json:"entities,omitempty"`
+	LinkPreviewOptions   *LinkPreviewOptions `json:"link_preview_options,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"`
+
+	SuggestedPostParameters *SuggestedPostParameters `json:"suggested_post_parameters,omitempty"`
+	ReplyParameters         *ReplyParameters         `json:"reply_parameters,omitempty"`
+	ReplyMarkup             *ReplyMarkup             `json:"reply_markup,omitempty"`
+}
+
+// SendMessage sends a text message.
+// See https://core.telegram.org/bots/api#sendmessage
+func (api *API) SendMessage(params SendMessageP) (Message, error) {
+	req := NewRequestWithChatID[Message, SendMessageP]("sendMessage", params, params.ChatID)
+	return req.Do(api)
+}
+
+// SendMessageWithContext is the context-aware variant of SendMessage.
+// It executes the same request but uses ctx for cancellation and deadlines.
+// See https://core.telegram.org/bots/api#sendmessage
+func (api *API) SendMessageWithContext(ctx context.Context, params SendMessageP) (Message, error) {
+	req := NewRequestWithChatID[Message, SendMessageP]("sendMessage", params, params.ChatID)
+	return req.DoWithContext(ctx, api)
+}
+
+// ForwardMessageP holds parameters for the forwardMessage method.
+// See https://core.telegram.org/bots/api#forwardmessage
+type ForwardMessageP struct {
+	ChatID                int64 `json:"chat_id"`
+	MessageThreadID       int   `json:"message_thread_id,omitempty"`
+	DirectMessagesTopicID int   `json:"direct_messages_topic_id,omitempty"`
+
+	MessageID           int   `json:"message_id,omitempty"`
+	FromChatID          int64 `json:"from_chat_id,omitempty"`
+	VideoStartTimestamp int   `json:"video_start_timestamp,omitempty"`
+	DisableNotification bool  `json:"disable_notification,omitempty"`
+	ProtectContent      bool  `json:"protect_content,omitempty"`
+
+	MessageEffectID         string                   `json:"message_effect_id,omitempty"`
+	SuggestedPostParameters *SuggestedPostParameters `json:"suggested_post_parameters,omitempty"`
+}
+
+// ForwardMessage forwards a message.
+// See https://core.telegram.org/bots/api#forwardmessage
+func (api *API) ForwardMessage(params ForwardMessageP) (Message, error) {
+	req := NewRequestWithChatID[Message]("forwardMessage", params, params.ChatID)
+	return req.Do(api)
+}
+
+// ForwardMessageWithContext is the context-aware variant of ForwardMessage.
+// It executes the same request but uses ctx for cancellation and deadlines.
+// See https://core.telegram.org/bots/api#forwardmessage
+func (api *API) ForwardMessageWithContext(ctx context.Context, params ForwardMessageP) (Message, error) {
+	req := NewRequestWithChatID[Message]("forwardMessage", params, params.ChatID)
+	return req.DoWithContext(ctx, api)
+}
+
+// ForwardMessagesP holds parameters for the forwardMessages method.
+// See https://core.telegram.org/bots/api#forwardmessages
+type ForwardMessagesP struct {
+	ChatID                int64 `json:"chat_id"`
+	MessageThreadID       int   `json:"message_thread_id,omitempty"`
+	DirectMessagesTopicID int   `json:"direct_messages_topic_id,omitempty"`
+
+	FromChatID          int64 `json:"from_chat_id,omitempty"`
+	MessageIDs          []int `json:"message_ids,omitempty"`
+	DisableNotification bool  `json:"disable_notification,omitempty"`
+	ProtectContent      bool  `json:"protect_content,omitempty"`
+}
+
+// ForwardMessages forwards multiple messages.
+// Returns an array of message IDs of the sent messages.
+// See https://core.telegram.org/bots/api#forwardmessages
+func (api *API) ForwardMessages(params ForwardMessagesP) ([]MessageID, error) {
+	req := NewRequestWithChatID[[]MessageID]("forwardMessages", params, params.ChatID)
+	return req.Do(api)
+}
+
+// ForwardMessagesWithContext is the context-aware variant of ForwardMessages.
+// It executes the same request but uses ctx for cancellation and deadlines.
+// See https://core.telegram.org/bots/api#forwardmessages
+func (api *API) ForwardMessagesWithContext(ctx context.Context, params ForwardMessagesP) ([]MessageID, error) {
+	req := NewRequestWithChatID[[]MessageID]("forwardMessages", params, params.ChatID)
+	return req.DoWithContext(ctx, api)
+}
+
+// CopyMessageP holds parameters for the copyMessage method.
+// See https://core.telegram.org/bots/api#copymessage
+type CopyMessageP struct {
+	ChatID                int64 `json:"chat_id"`
+	MessageThreadID       int   `json:"message_thread_id,omitempty"`
+	DirectMessagesTopicID int   `json:"direct_messages_topic_id,omitempty"`
+
+	FromChatID          int64     `json:"from_chat_id"`
+	MessageID           int       `json:"message_id"`
+	VideoStartTimestamp int       `json:"video_start_timestamp,omitempty"`
+	Caption             string    `json:"caption,omitempty"`
+	ParseMode           ParseMode `json:"parse_mode,omitempty"`
+
+	CaptionEntities       []MessageEntity `json:"caption_entities,omitempty"`
+	ShowCaptionAboveMedia bool            `json:"show_caption_above_media,omitempty"`
+	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"`
+}
+
+// CopyMessage copies a message.
+// Returns the MessageID of the sent copy.
+// See https://core.telegram.org/bots/api#copymessage
+func (api *API) CopyMessage(params CopyMessageP) (int, error) {
+	msgID, err := NewRequestWithChatID[MessageID]("copyMessage", params, params.ChatID).Do(api)
+	if err != nil {
+		return 0, err
+	}
+	return msgID.MessageID, nil
+}
+
+// CopyMessageWithContext is the context-aware variant of CopyMessage.
+// It executes the same request but uses ctx for cancellation and deadlines.
+// See https://core.telegram.org/bots/api#copymessage
+func (api *API) CopyMessageWithContext(ctx context.Context, params CopyMessageP) (int, error) {
+	msgID, err := NewRequestWithChatID[MessageID]("copyMessage", params, params.ChatID).DoWithContext(ctx, api)
+	if err != nil {
+		return 0, err
+	}
+	return msgID.MessageID, nil
+}
+
+// CopyMessagesP holds parameters for the copyMessages method.
+// See https://core.telegram.org/bots/api#copymessages
+type CopyMessagesP struct {
+	ChatID                int64 `json:"chat_id"`
+	MessageThreadID       int   `json:"message_thread_id,omitempty"`
+	DirectMessagesTopicID int   `json:"direct_messages_topic_id,omitempty"`
+
+	FromChatID          int64 `json:"from_chat_id,omitempty"`
+	MessageIDs          []int `json:"message_ids,omitempty"`
+	DisableNotification bool  `json:"disable_notification,omitempty"`
+	ProtectContent      bool  `json:"protect_content,omitempty"`
+	RemoveCaption       bool  `json:"remove_caption,omitempty"`
+}
+
+// CopyMessages copies multiple messages.
+// Returns an array of message IDs of the sent copies.
+// See https://core.telegram.org/bots/api#copymessages
+func (api *API) CopyMessages(params CopyMessagesP) ([]MessageID, error) {
+	req := NewRequestWithChatID[[]MessageID]("copyMessages", params, params.ChatID)
+	return req.Do(api)
+}
+
+// CopyMessagesWithContext is the context-aware variant of CopyMessages.
+// It executes the same request but uses ctx for cancellation and deadlines.
+// See https://core.telegram.org/bots/api#copymessages
+func (api *API) CopyMessagesWithContext(ctx context.Context, params CopyMessagesP) ([]MessageID, error) {
+	req := NewRequestWithChatID[[]MessageID]("copyMessages", params, params.ChatID)
+	return req.DoWithContext(ctx, api)
+}
+
+// SendLocationP holds parameters for the sendLocation method.
+// See https://core.telegram.org/bots/api#sendlocation
+type SendLocationP 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"`
+
+	Latitude             float64 `json:"latitude"`
+	Longitude            float64 `json:"longitude"`
+	HorizontalAccuracy   float64 `json:"horizontal_accuracy,omitempty"`
+	LivePeriod           int     `json:"live_period,omitempty"`
+	Heading              int     `json:"heading,omitempty"`
+	ProximityAlertRadius int     `json:"proximity_alert_radius,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"`
+}
+
+// SendLocation sends a point on the map.
+// See https://core.telegram.org/bots/api#sendlocation
+func (api *API) SendLocation(params SendLocationP) (Message, error) {
+	req := NewRequestWithChatID[Message]("sendLocation", params, params.ChatID)
+	return req.Do(api)
+}
+
+// SendLocationWithContext is the context-aware variant of SendLocation.
+// It executes the same request but uses ctx for cancellation and deadlines.
+// See https://core.telegram.org/bots/api#sendlocation
+func (api *API) SendLocationWithContext(ctx context.Context, params SendLocationP) (Message, error) {
+	req := NewRequestWithChatID[Message]("sendLocation", params, params.ChatID)
+	return req.DoWithContext(ctx, api)
+}
+
+// SendVenueP holds parameters for the sendVenue method.
+// See https://core.telegram.org/bots/api#sendvenue
+type SendVenueP 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"`
+
+	Latitude        float64 `json:"latitude"`
+	Longitude       float64 `json:"longitude"`
+	Title           string  `json:"title"`
+	Address         string  `json:"address"`
+	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"`
+
+	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"`
+}
+
+// SendVenue sends information about a venue.
+// See https://core.telegram.org/bots/api#sendvenue
+func (api *API) SendVenue(params SendVenueP) (Message, error) {
+	req := NewRequestWithChatID[Message]("sendVenue", params, params.ChatID)
+	return req.Do(api)
+}
+
+// SendVenueWithContext is the context-aware variant of SendVenue.
+// It executes the same request but uses ctx for cancellation and deadlines.
+// See https://core.telegram.org/bots/api#sendvenue
+func (api *API) SendVenueWithContext(ctx context.Context, params SendVenueP) (Message, error) {
+	req := NewRequestWithChatID[Message]("sendVenue", params, params.ChatID)
+	return req.DoWithContext(ctx, api)
+}
+
+// SendContactP holds parameters for the sendContact method.
+// See https://core.telegram.org/bots/api#sendcontact
+type SendContactP 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"`
+
+	PhoneNumber string `json:"phone_number"`
+	FirstName   string `json:"first_name"`
+	LastName    string `json:"last_name,omitempty"`
+	Vcard       string `json:"vcard"`
+
+	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"`
+}
+
+// SendContact sends a phone contact.
+// See https://core.telegram.org/bots/api#sendcontact
+func (api *API) SendContact(params SendContactP) (Message, error) {
+	req := NewRequestWithChatID[Message]("sendContact", params, params.ChatID)
+	return req.Do(api)
+}
+
+// SendContactWithContext is the context-aware variant of SendContact.
+// It executes the same request but uses ctx for cancellation and deadlines.
+// See https://core.telegram.org/bots/api#sendcontact
+func (api *API) SendContactWithContext(ctx context.Context, params SendContactP) (Message, error) {
+	req := NewRequestWithChatID[Message]("sendContact", params, params.ChatID)
+	return req.DoWithContext(ctx, api)
+}
+
+// SendPollP holds parameters for the sendPoll method.
+// See https://core.telegram.org/bots/api#sendpoll
+type SendPollP struct {
+	BusinessConnectionID string `json:"business_connection_id,omitempty"`
+	ChatID               int64  `json:"chat_id"`
+	MessageThreadID      int    `json:"message_thread_id,omitempty"`
+
+	Question              string            `json:"question"`
+	QuestionParseMode     ParseMode         `json:"question_parse_mode,omitempty"`
+	QuestionEntities      []MessageEntity   `json:"question_entities,omitempty"`
+	Options               []InputPollOption `json:"options"`
+	IsAnonymous           bool              `json:"is_anonymous,omitempty"`
+	Type                  PollType          `json:"type"`
+	AllowsMultipleAnswers bool              `json:"allows_multiple_answers,omitempty"`
+	CorrectOptionID       int               `json:"correct_option_id,omitempty"`
+	Explanation           string            `json:"explanation,omitempty"`
+	ExplanationParseMode  ParseMode         `json:"explanation_parse_mode,omitempty"`
+	ExplanationEntities   []MessageEntity   `json:"explanation_entities,omitempty"`
+	OpenPeriod            int               `json:"open_period,omitempty"`
+	CloseDate             int               `json:"close_date"`
+	IsClosed              bool              `json:"is_closed,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"`
+
+	ReplyParameters *ReplyParameters `json:"reply_parameters,omitempty"`
+	ReplyMarkup     *ReplyMarkup     `json:"reply_markup,omitempty"`
+}
+
+// SendPoll sends a native poll.
+// See https://core.telegram.org/bots/api#sendpoll
+func (api *API) SendPoll(params SendPollP) (Message, error) {
+	req := NewRequestWithChatID[Message]("sendPoll", params, params.ChatID)
+	return req.Do(api)
+}
+
+// SendPollWithContext is the context-aware variant of SendPoll.
+// It executes the same request but uses ctx for cancellation and deadlines.
+// See https://core.telegram.org/bots/api#sendpoll
+func (api *API) SendPollWithContext(ctx context.Context, params SendPollP) (Message, error) {
+	req := NewRequestWithChatID[Message]("sendPoll", params, params.ChatID)
+	return req.DoWithContext(ctx, api)
+}
+
+// SendChecklistP holds parameters for the sendChecklist method.
+// See https://core.telegram.org/bots/api#sendchecklist
+type SendChecklistP struct {
+	BusinessConnectionID string         `json:"business_connection_id"`
+	ChatID               int64          `json:"chat_id"`
+	Checklist            InputChecklist `json:"checklist"`
+
+	DisableNotification bool   `json:"disable_notification,omitempty"`
+	ProtectContent      bool   `json:"protect_content,omitempty"`
+	MessageEffectID     string `json:"message_effect_id,omitempty"`
+
+	ReplyParameters *ReplyParameters `json:"reply_parameters,omitempty"`
+	ReplyMarkup     *ReplyMarkup     `json:"reply_markup,omitempty"`
+}
+
+// SendChecklist sends a checklist.
+// See https://core.telegram.org/bots/api#sendchecklist
+func (api *API) SendChecklist(params SendChecklistP) (Message, error) {
+	req := NewRequestWithChatID[Message]("sendChecklist", params, params.ChatID)
+	return req.Do(api)
+}
+
+// SendChecklistWithContext is the context-aware variant of SendChecklist.
+// It executes the same request but uses ctx for cancellation and deadlines.
+// See https://core.telegram.org/bots/api#sendchecklist
+func (api *API) SendChecklistWithContext(ctx context.Context, params SendChecklistP) (Message, error) {
+	req := NewRequestWithChatID[Message]("sendChecklist", params, params.ChatID)
+	return req.DoWithContext(ctx, api)
+}
+
+// SendDiceP holds parameters for the sendDice method.
+// See https://core.telegram.org/bots/api#senddice
+type SendDiceP 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"`
+
+	Emoji string `json:"emoji,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"`
+}
+
+// SendDice sends a dice, which will have a random value.
+// See https://core.telegram.org/bots/api#senddice
+func (api *API) SendDice(params SendDiceP) (Message, error) {
+	req := NewRequestWithChatID[Message]("sendDice", params, params.ChatID)
+	return req.Do(api)
+}
+
+// SendDiceWithContext is the context-aware variant of SendDice.
+// It executes the same request but uses ctx for cancellation and deadlines.
+// See https://core.telegram.org/bots/api#senddice
+func (api *API) SendDiceWithContext(ctx context.Context, params SendDiceP) (Message, error) {
+	req := NewRequestWithChatID[Message]("sendDice", params, params.ChatID)
+	return req.DoWithContext(ctx, api)
+}
+
+// SendMessageDraftP holds parameters for the sendMessageDraft method.
+// See https://core.telegram.org/bots/api#sendmessagedraft
+type SendMessageDraftP struct {
+	ChatID          int64           `json:"chat_id"`
+	MessageThreadID int             `json:"message_thread_id,omitempty"`
+	DraftID         uint64          `json:"draft_id"`
+	Text            string          `json:"text"`
+	ParseMode       ParseMode       `json:"parse_mode,omitempty"`
+	Entities        []MessageEntity `json:"entities,omitempty"`
+}
+
+// SendMessageDraft sends or updates a draft message in the target chat.
+// Returns True on success.
+// See https://core.telegram.org/bots/api#sendmessagedraft
+func (api *API) SendMessageDraft(params SendMessageDraftP) (bool, error) {
+	req := NewRequestWithChatID[bool]("sendMessageDraft", params, params.ChatID)
+	return req.Do(api)
+}
+
+// SendMessageDraftWithContext is the context-aware variant of SendMessageDraft.
+// It executes the same request but uses ctx for cancellation and deadlines.
+// See https://core.telegram.org/bots/api#sendmessagedraft
+func (api *API) SendMessageDraftWithContext(ctx context.Context, params SendMessageDraftP) (bool, error) {
+	req := NewRequestWithChatID[bool]("sendMessageDraft", params, params.ChatID)
+	return req.DoWithContext(ctx, api)
+}
+
+// SendChatActionP holds parameters for the sendChatAction method.
+// See https://core.telegram.org/bots/api#sendchataction
+type SendChatActionP struct {
+	BusinessConnectionID string         `json:"business_connection_id,omitempty"`
+	ChatID               int64          `json:"chat_id"`
+	MessageThreadID      int            `json:"message_thread_id,omitempty"`
+	Action               ChatActionType `json:"action"`
+}
+
+// SendChatAction sends a chat action (typing, uploading photo, etc.).
+// Returns True on success.
+// See https://core.telegram.org/bots/api#sendchataction
+func (api *API) SendChatAction(params SendChatActionP) (bool, error) {
+	req := NewRequestWithChatID[bool]("sendChatAction", params, params.ChatID)
+	return req.Do(api)
+}
+
+// SendChatActionWithContext is the context-aware variant of SendChatAction.
+// It executes the same request but uses ctx for cancellation and deadlines.
+// See https://core.telegram.org/bots/api#sendchataction
+func (api *API) SendChatActionWithContext(ctx context.Context, params SendChatActionP) (bool, error) {
+	req := NewRequestWithChatID[bool]("sendChatAction", params, params.ChatID)
+	return req.DoWithContext(ctx, api)
+}
+
+// SetMessageReactionP holds parameters for the setMessageReaction method.
+// See https://core.telegram.org/bots/api#setmessagereaction
+type SetMessageReactionP struct {
+	ChatID    int64          `json:"chat_id"`
+	MessageId int            `json:"message_id"`
+	Reaction  []ReactionType `json:"reaction"`
+	IsBig     bool           `json:"is_big,omitempty"`
+}
+
+// SetMessageReaction changes the chosen reaction on a message.
+// Returns True on success.
+// See https://core.telegram.org/bots/api#setmessagereaction
+func (api *API) SetMessageReaction(params SetMessageReactionP) (bool, error) {
+	req := NewRequestWithChatID[bool]("setMessageReaction", params, params.ChatID)
+	return req.Do(api)
+}
+
+// SetMessageReactionWithContext is the context-aware variant of SetMessageReaction.
+// It executes the same request but uses ctx for cancellation and deadlines.
+// See https://core.telegram.org/bots/api#setmessagereaction
+func (api *API) SetMessageReactionWithContext(ctx context.Context, params SetMessageReactionP) (bool, error) {
+	req := NewRequestWithChatID[bool]("setMessageReaction", params, params.ChatID)
+	return req.DoWithContext(ctx, api)
+}
+
+// EditMessageTextP holds parameters for the editMessageText method.
+// See https://core.telegram.org/bots/api#editmessagetext
+type EditMessageTextP struct {
+	BusinessConnectionID string              `json:"business_connection_id,omitempty"`
+	ChatID               int64               `json:"chat_id,omitempty"`
+	MessageID            int                 `json:"message_id,omitempty"`
+	InlineMessageID      string              `json:"inline_message_id,omitempty"`
+	Text                 string              `json:"text"`
+	ParseMode            ParseMode           `json:"parse_mode,omitempty"`
+	Entities             []MessageEntity     `json:"entities,omitempty"`
+	LinkPreviewOptions   *LinkPreviewOptions `json:"link_preview_options,omitempty"`
+	ReplyMarkup          *ReplyMarkup        `json:"reply_markup,omitempty"`
+}
+
+// EditMessageText edits text messages.
+// If inline_message_id is provided, returns a boolean success flag;
+// otherwise returns the edited Message.
+// See https://core.telegram.org/bots/api#editmessagetext
+func (api *API) EditMessageText(params EditMessageTextP) (Message, bool, error) {
+	var zero Message
+	if params.InlineMessageID != "" {
+		req := NewRequestWithChatID[bool]("editMessageText", params, params.ChatID)
+		res, err := req.Do(api)
+		return zero, res, err
+	}
+	req := NewRequestWithChatID[Message]("editMessageText", params, params.ChatID)
+	res, err := req.Do(api)
+	return res, false, err
+}
+
+// EditMessageTextWithContext is the context-aware variant of EditMessageText.
+// It executes the same request but uses ctx for cancellation and deadlines.
+// See https://core.telegram.org/bots/api#editmessagetext
+func (api *API) EditMessageTextWithContext(ctx context.Context, params EditMessageTextP) (Message, bool, error) {
+	var zero Message
+	if params.InlineMessageID != "" {
+		req := NewRequestWithChatID[bool]("editMessageText", params, params.ChatID)
+		res, err := req.DoWithContext(ctx, api)
+		return zero, res, err
+	}
+	req := NewRequestWithChatID[Message]("editMessageText", params, params.ChatID)
+	res, err := req.DoWithContext(ctx, api)
+	return res, false, err
+}
+
+// EditMessageCaptionP holds parameters for the editMessageCaption method.
+// See https://core.telegram.org/bots/api#editmessagecaption
+type EditMessageCaptionP struct {
+	BusinessConnectionID  string          `json:"business_connection_id,omitempty"`
+	ChatID                int64           `json:"chat_id,omitempty"`
+	MessageID             int             `json:"message_id,omitempty"`
+	InlineMessageID       string          `json:"inline_message_id,omitempty"`
+	Caption               string          `json:"caption"`
+	ParseMode             ParseMode       `json:"parse_mode,omitempty"`
+	CaptionEntities       []MessageEntity `json:"caption_entities,omitempty"`
+	ShowCaptionAboveMedia bool            `json:"show_caption_above_media,omitempty"`
+	ReplyMarkup           *ReplyMarkup    `json:"reply_markup,omitempty"`
+}
+
+// EditMessageCaption edits captions of messages.
+// If inline_message_id is provided, returns a boolean success flag;
+// otherwise returns the edited Message.
+// See https://core.telegram.org/bots/api#editmessagecaption
+func (api *API) EditMessageCaption(params EditMessageCaptionP) (Message, bool, error) {
+	var zero Message
+	if params.InlineMessageID != "" {
+		req := NewRequestWithChatID[bool]("editMessageCaption", params, params.ChatID)
+		res, err := req.Do(api)
+		return zero, res, err
+	}
+	req := NewRequestWithChatID[Message]("editMessageCaption", params, params.ChatID)
+	res, err := req.Do(api)
+	return res, false, err
+}
+
+// EditMessageCaptionWithContext is the context-aware variant of EditMessageCaption.
+// It executes the same request but uses ctx for cancellation and deadlines.
+// See https://core.telegram.org/bots/api#editmessagecaption
+func (api *API) EditMessageCaptionWithContext(ctx context.Context, params EditMessageCaptionP) (Message, bool, error) {
+	var zero Message
+	if params.InlineMessageID != "" {
+		req := NewRequestWithChatID[bool]("editMessageCaption", params, params.ChatID)
+		res, err := req.DoWithContext(ctx, api)
+		return zero, res, err
+	}
+	req := NewRequestWithChatID[Message]("editMessageCaption", params, params.ChatID)
+	res, err := req.DoWithContext(ctx, api)
+	return res, false, err
+}
+
+// EditMessageMediaP holds parameters for the editMessageMedia method.
+// See https://core.telegram.org/bots/api#editmessagemedia
+type EditMessageMediaP struct {
+	BusinessConnectionID string                `json:"business_connection_id,omitempty"`
+	ChatID               int64                 `json:"chat_id,omitempty"`
+	MessageID            int                   `json:"message_id,omitempty"`
+	InlineMessageID      string                `json:"inline_message_id,omitempty"`
+	Media                InputMedia            `json:"media"`
+	ReplyMarkup          *InlineKeyboardMarkup `json:"reply_markup,omitempty"`
+}
+
+// EditMessageMedia edits media messages.
+// If inline_message_id is provided, returns a boolean success flag;
+// otherwise returns the edited Message.
+// See https://core.telegram.org/bots/api#editmessagemedia
+func (api *API) EditMessageMedia(params EditMessageMediaP) (Message, bool, error) {
+	var zero Message
+	if params.InlineMessageID != "" {
+		req := NewRequestWithChatID[bool]("editMessageMedia", params, params.ChatID)
+		res, err := req.Do(api)
+		return zero, res, err
+	}
+	req := NewRequestWithChatID[Message]("editMessageMedia", params, params.ChatID)
+	res, err := req.Do(api)
+	return res, false, err
+}
+
+// EditMessageMediaWithContext is the context-aware variant of EditMessageMedia.
+// It executes the same request but uses ctx for cancellation and deadlines.
+// See https://core.telegram.org/bots/api#editmessagemedia
+func (api *API) EditMessageMediaWithContext(ctx context.Context, params EditMessageMediaP) (Message, bool, error) {
+	var zero Message
+	if params.InlineMessageID != "" {
+		req := NewRequestWithChatID[bool]("editMessageMedia", params, params.ChatID)
+		res, err := req.DoWithContext(ctx, api)
+		return zero, res, err
+	}
+	req := NewRequestWithChatID[Message]("editMessageMedia", params, params.ChatID)
+	res, err := req.DoWithContext(ctx, api)
+	return res, false, err
+}
+
+// EditMessageLiveLocationP holds parameters for the editMessageLiveLocation method.
+// See https://core.telegram.org/bots/api#editmessagelivelocation
+type EditMessageLiveLocationP struct {
+	BusinessConnectionID string `json:"business_connection_id,omitempty"`
+	ChatID               int64  `json:"chat_id,omitempty"`
+	MessageID            int    `json:"message_id,omitempty"`
+	InlineMessageID      string `json:"inline_message_id,omitempty"`
+
+	Latitude             float64               `json:"latitude"`
+	Longitude            float64               `json:"longitude"`
+	LivePeriod           int                   `json:"live_period,omitempty"`
+	HorizontalAccuracy   float64               `json:"horizontal_accuracy,omitempty"`
+	Heading              int                   `json:"heading,omitempty"`
+	ProximityAlertRadius int                   `json:"proximity_alert_radius,omitempty"`
+	ReplyMarkup          *InlineKeyboardMarkup `json:"reply_markup,omitempty"`
+}
+
+// EditMessageLiveLocation edits live location messages.
+// If inline_message_id is provided, returns a boolean success flag;
+// otherwise returns the edited Message.
+// See https://core.telegram.org/bots/api#editmessagelivelocation
+func (api *API) EditMessageLiveLocation(params EditMessageLiveLocationP) (Message, bool, error) {
+	var zero Message
+	if params.InlineMessageID != "" {
+		req := NewRequestWithChatID[bool]("editMessageLiveLocation", params, params.ChatID)
+		res, err := req.Do(api)
+		return zero, res, err
+	}
+	req := NewRequestWithChatID[Message]("editMessageLiveLocation", params, params.ChatID)
+	res, err := req.Do(api)
+	return res, false, err
+}
+
+// EditMessageLiveLocationWithContext is the context-aware variant of EditMessageLiveLocation.
+// It executes the same request but uses ctx for cancellation and deadlines.
+// See https://core.telegram.org/bots/api#editmessagelivelocation
+func (api *API) EditMessageLiveLocationWithContext(ctx context.Context, params EditMessageLiveLocationP) (Message, bool, error) {
+	var zero Message
+	if params.InlineMessageID != "" {
+		req := NewRequestWithChatID[bool]("editMessageLiveLocation", params, params.ChatID)
+		res, err := req.DoWithContext(ctx, api)
+		return zero, res, err
+	}
+	req := NewRequestWithChatID[Message]("editMessageLiveLocation", params, params.ChatID)
+	res, err := req.DoWithContext(ctx, api)
+	return res, false, err
+}
+
+// StopMessageLiveLocationP holds parameters for the stopMessageLiveLocation method.
+// See https://core.telegram.org/bots/api#stopmessagelivelocation
+type StopMessageLiveLocationP struct {
+	BusinessConnectionID string                `json:"business_connection_id,omitempty"`
+	ChatID               int64                 `json:"chat_id,omitempty"`
+	MessageID            int                   `json:"message_id,omitempty"`
+	InlineMessageID      string                `json:"inline_message_id,omitempty"`
+	ReplyMarkup          *InlineKeyboardMarkup `json:"reply_markup,omitempty"`
+}
+
+// StopMessageLiveLocation stops a live location message.
+// If inline_message_id is provided, returns a boolean success flag;
+// otherwise returns the edited Message.
+// See https://core.telegram.org/bots/api#stopmessagelivelocation
+func (api *API) StopMessageLiveLocation(params StopMessageLiveLocationP) (Message, bool, error) {
+	var zero Message
+	if params.InlineMessageID != "" {
+		req := NewRequestWithChatID[bool]("stopMessageLiveLocation", params, params.ChatID)
+		res, err := req.Do(api)
+		return zero, res, err
+	}
+	req := NewRequestWithChatID[Message]("stopMessageLiveLocation", params, params.ChatID)
+	res, err := req.Do(api)
+	return res, false, err
+}
+
+// StopMessageLiveLocationWithContext is the context-aware variant of StopMessageLiveLocation.
+// It executes the same request but uses ctx for cancellation and deadlines.
+// See https://core.telegram.org/bots/api#stopmessagelivelocation
+func (api *API) StopMessageLiveLocationWithContext(ctx context.Context, params StopMessageLiveLocationP) (Message, bool, error) {
+	var zero Message
+	if params.InlineMessageID != "" {
+		req := NewRequestWithChatID[bool]("stopMessageLiveLocation", params, params.ChatID)
+		res, err := req.DoWithContext(ctx, api)
+		return zero, res, err
+	}
+	req := NewRequestWithChatID[Message]("stopMessageLiveLocation", params, params.ChatID)
+	res, err := req.DoWithContext(ctx, api)
+	return res, false, err
+}
+
+// EditMessageChecklistP holds parameters for the editMessageChecklist method.
+type EditMessageChecklistP struct {
+	BusinessConnectionID string                `json:"business_connection_id"`
+	ChatID               int64                 `json:"chat_id"`
+	MessageID            int                   `json:"message_id"`
+	Checklist            InputChecklist        `json:"checklist"`
+	ReplyMarkup          *InlineKeyboardMarkup `json:"reply_markup,omitempty"`
+}
+
+// EditMessageChecklist edits a checklist message.
+// See https://core.telegram.org/bots/api#editmessagechecklist
+func (api *API) EditMessageChecklist(params EditMessageChecklistP) (Message, error) {
+	req := NewRequestWithChatID[Message]("editMessageChecklist", params, params.ChatID)
+	return req.Do(api)
+}
+
+// EditMessageChecklistWithContext is the context-aware variant of EditMessageChecklist.
+// It executes the same request but uses ctx for cancellation and deadlines.
+// See https://core.telegram.org/bots/api#editmessagechecklist
+func (api *API) EditMessageChecklistWithContext(ctx context.Context, params EditMessageChecklistP) (Message, error) {
+	req := NewRequestWithChatID[Message]("editMessageChecklist", params, params.ChatID)
+	return req.DoWithContext(ctx, api)
+}
+
+// EditMessageReplyMarkupP holds parameters for the editMessageReplyMarkup method.
+// See https://core.telegram.org/bots/api#editmessagereplymarkup
+type EditMessageReplyMarkupP struct {
+	BusinessConnectionID string                `json:"business_connection_id,omitempty"`
+	ChatID               int64                 `json:"chat_id,omitempty"`
+	MessageID            int                   `json:"message_id,omitempty"`
+	InlineMessageID      string                `json:"inline_message_id,omitempty"`
+	ReplyMarkup          *InlineKeyboardMarkup `json:"reply_markup,omitempty"`
+}
+
+// EditMessageReplyMarkup edits only the reply markup of messages.
+// If inline_message_id is provided, returns a boolean success flag;
+// otherwise returns the edited Message.
+// See https://core.telegram.org/bots/api#editmessagereplymarkup
+func (api *API) EditMessageReplyMarkup(params EditMessageReplyMarkupP) (Message, bool, error) {
+	var zero Message
+	if params.InlineMessageID != "" {
+		req := NewRequestWithChatID[bool]("editMessageReplyMarkup", params, params.ChatID)
+		res, err := req.Do(api)
+		return zero, res, err
+	}
+	req := NewRequestWithChatID[Message]("editMessageReplyMarkup", params, params.ChatID)
+	res, err := req.Do(api)
+	return res, false, err
+}
+
+// EditMessageReplyMarkupWithContext is the context-aware variant of EditMessageReplyMarkup.
+// It executes the same request but uses ctx for cancellation and deadlines.
+// See https://core.telegram.org/bots/api#editmessagereplymarkup
+func (api *API) EditMessageReplyMarkupWithContext(ctx context.Context, params EditMessageReplyMarkupP) (Message, bool, error) {
+	var zero Message
+	if params.InlineMessageID != "" {
+		req := NewRequestWithChatID[bool]("editMessageReplyMarkup", params, params.ChatID)
+		res, err := req.DoWithContext(ctx, api)
+		return zero, res, err
+	}
+	req := NewRequestWithChatID[Message]("editMessageReplyMarkup", params, params.ChatID)
+	res, err := req.DoWithContext(ctx, api)
+	return res, false, err
+}
+
+// StopPollP holds parameters for the stopPoll method.
+// See https://core.telegram.org/bots/api#stoppoll
+type StopPollP struct {
+	BusinessConnectionID string                `json:"business_connection_id,omitempty"`
+	ChatID               int64                 `json:"chat_id"`
+	MessageID            int                   `json:"message_id"`
+	ReplyMarkup          *InlineKeyboardMarkup `json:"reply_markup,omitempty"`
+}
+
+// StopPoll stops a poll that was sent by the bot.
+// Returns the stopped Poll.
+// See https://core.telegram.org/bots/api#stoppoll
+func (api *API) StopPoll(params StopPollP) (Poll, error) {
+	req := NewRequestWithChatID[Poll]("stopPoll", params, params.ChatID)
+	return req.Do(api)
+}
+
+// StopPollWithContext is the context-aware variant of StopPoll.
+// It executes the same request but uses ctx for cancellation and deadlines.
+// See https://core.telegram.org/bots/api#stoppoll
+func (api *API) StopPollWithContext(ctx context.Context, params StopPollP) (Poll, error) {
+	req := NewRequestWithChatID[Poll]("stopPoll", params, params.ChatID)
+	return req.DoWithContext(ctx, api)
+}
+
+// ApproveSuggestedPostP holds parameters for the approveSuggestedPost method.
+// See https://core.telegram.org/bots/api#approvesuggestedpost
+type ApproveSuggestedPostP struct {
+	ChatID    int64 `json:"chat_id"`
+	MessageID int   `json:"message_id"`
+	SendDate  int   `json:"send_date,omitempty"`
+}
+
+// ApproveSuggestedPost approves a suggested channel post.
+// Returns True on success.
+// See https://core.telegram.org/bots/api#approvesuggestedpost
+func (api *API) ApproveSuggestedPost(params ApproveSuggestedPostP) (bool, error) {
+	req := NewRequestWithChatID[bool]("approveSuggestedPost", params, params.ChatID)
+	return req.Do(api)
+}
+
+// ApproveSuggestedPostWithContext is the context-aware variant of ApproveSuggestedPost.
+// It executes the same request but uses ctx for cancellation and deadlines.
+// See https://core.telegram.org/bots/api#approvesuggestedpost
+func (api *API) ApproveSuggestedPostWithContext(ctx context.Context, params ApproveSuggestedPostP) (bool, error) {
+	req := NewRequestWithChatID[bool]("approveSuggestedPost", params, params.ChatID)
+	return req.DoWithContext(ctx, api)
+}
+
+// DeclineSuggestedPostP holds parameters for the declineSuggestedPost method.
+// See https://core.telegram.org/bots/api#declinesuggestedpost
+type DeclineSuggestedPostP struct {
+	ChatID    int64  `json:"chat_id"`
+	MessageID int    `json:"message_id"`
+	Comment   string `json:"comment,omitempty"`
+}
+
+// DeclineSuggestedPost declines a suggested channel post.
+// Returns True on success.
+// See https://core.telegram.org/bots/api#declinesuggestedpost
+func (api *API) DeclineSuggestedPost(params DeclineSuggestedPostP) (bool, error) {
+	req := NewRequestWithChatID[bool]("declineSuggestedPost", params, params.ChatID)
+	return req.Do(api)
+}
+
+// DeclineSuggestedPostWithContext is the context-aware variant of DeclineSuggestedPost.
+// It executes the same request but uses ctx for cancellation and deadlines.
+// See https://core.telegram.org/bots/api#declinesuggestedpost
+func (api *API) DeclineSuggestedPostWithContext(ctx context.Context, params DeclineSuggestedPostP) (bool, error) {
+	req := NewRequestWithChatID[bool]("declineSuggestedPost", params, params.ChatID)
+	return req.DoWithContext(ctx, api)
+}
+
+// DeleteMessageP holds parameters for the deleteMessage method.
+// See https://core.telegram.org/bots/api#deletemessage
+type DeleteMessageP struct {
+	ChatID    int64 `json:"chat_id"`
+	MessageID int   `json:"message_id"`
+}
+
+// DeleteMessage deletes a message.
+// Returns True on success.
+// See https://core.telegram.org/bots/api#deletemessage
+func (api *API) DeleteMessage(params DeleteMessageP) (bool, error) {
+	req := NewRequestWithChatID[bool]("deleteMessage", params, params.ChatID)
+	return req.Do(api)
+}
+
+// DeleteMessageWithContext is the context-aware variant of DeleteMessage.
+// It executes the same request but uses ctx for cancellation and deadlines.
+// See https://core.telegram.org/bots/api#deletemessage
+func (api *API) DeleteMessageWithContext(ctx context.Context, params DeleteMessageP) (bool, error) {
+	req := NewRequestWithChatID[bool]("deleteMessage", params, params.ChatID)
+	return req.DoWithContext(ctx, api)
+}
+
+// DeleteMessagesP holds parameters for the deleteMessages method.
+// See https://core.telegram.org/bots/api#deletemessages
+type DeleteMessagesP struct {
+	ChatID     int64 `json:"chat_id"`
+	MessageIDs []int `json:"message_ids"`
+}
+
+// DeleteMessages deletes multiple messages at once.
+// Returns True on success.
+// See https://core.telegram.org/bots/api#deletemessages
+func (api *API) DeleteMessages(params DeleteMessagesP) (bool, error) {
+	req := NewRequestWithChatID[bool]("deleteMessages", params, params.ChatID)
+	return req.Do(api)
+}
+
+// DeleteMessagesWithContext is the context-aware variant of DeleteMessages.
+// It executes the same request but uses ctx for cancellation and deadlines.
+// See https://core.telegram.org/bots/api#deletemessages
+func (api *API) DeleteMessagesWithContext(ctx context.Context, params DeleteMessagesP) (bool, error) {
+	req := NewRequestWithChatID[bool]("deleteMessages", params, params.ChatID)
+	return req.DoWithContext(ctx, api)
+}
+
+// AnswerCallbackQueryP holds parameters for the answerCallbackQuery method.
+// See https://core.telegram.org/bots/api#answercallbackquery
+type AnswerCallbackQueryP struct {
+	CallbackQueryID string `json:"callback_query_id"`
+	Text            string `json:"text,omitempty"`
+	ShowAlert       bool   `json:"show_alert,omitempty"`
+	URL             string `json:"url,omitempty"`
+	CacheTime       int    `json:"cache_time,omitempty"`
+}
+
+// AnswerCallbackQuery sends answers to callback queries sent from inline keyboards.
+// Returns True on success.
+// See https://core.telegram.org/bots/api#answercallbackquery
+func (api *API) AnswerCallbackQuery(params AnswerCallbackQueryP) (bool, error) {
+	req := NewRequest[bool]("answerCallbackQuery", params)
+	return req.Do(api)
+}
+
+// AnswerCallbackQueryWithContext is the context-aware variant of AnswerCallbackQuery.
+// It executes the same request but uses ctx for cancellation and deadlines.
+// See https://core.telegram.org/bots/api#answercallbackquery
+func (api *API) AnswerCallbackQueryWithContext(ctx context.Context, params AnswerCallbackQueryP) (bool, error) {
+	req := NewRequest[bool]("answerCallbackQuery", params)
+	return req.DoWithContext(ctx, api)
+}

tgapi/messages_types.go

@@ -0,0 +1,394 @@
+package tgapi
+
+import "git.scuroneko.dev/scuroneko/extypes"
+
+// MessageID represents a message identifier wrapper returned by some API methods.
+type MessageID struct {
+	MessageID int `json:"message_id"`
+}
+
+// MessageReplyMarkup represents an inline keyboard markup for a message.
+// It is used in the Message type.
+type MessageReplyMarkup struct {
+	InlineKeyboard [][]InlineKeyboardButton `json:"inline_keyboard"`
+}
+
+// DirectMessageTopic represents a forum topic in a direct message.
+type DirectMessageTopic struct {
+	TopicID int64 `json:"topic_id"`
+	User    *User `json:"user,omitempty"`
+}
+
+// Message represents a Telegram message.
+// See https://core.telegram.org/bots/api#message
+type Message struct {
+	MessageID            int                 `json:"message_id"`
+	MessageThreadID      int                 `json:"message_thread_id,omitempty"`
+	DirectMessageTopic   *DirectMessageTopic `json:"direct_message_topic,omitempty"`
+	BusinessConnectionId string              `json:"business_connection_id,omitempty"`
+	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"`
+	SenderTag         string `json:"sender_tag,omitempty"`
+	Chat              *Chat  `json:"chat,omitempty"`
+
+	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"`
+
+	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"`
+
+	Entities           []MessageEntity     `json:"entities,omitempty"`
+	LinkPreviewOptions *LinkPreviewOptions `json:"link_preview_options,omitempty"`
+	SuggestedPostInfo  *SuggestedPostInfo  `json:"suggested_post_info,omitempty"`
+
+	EffectID string `json:"effect_id,omitempty"`
+}
+
+// InaccessibleMessage describes a message that was deleted or is otherwise inaccessible.
+// See https://core.telegram.org/bots/api#inaccessiblemessage
+type InaccessibleMessage struct {
+	Chat      Chat `json:"chat"`
+	MessageID int  `json:"message_id"`
+	Date      int  `json:"date"`
+}
+
+// MaybeInaccessibleMessage is a union type that can be either Message or InaccessibleMessage.
+// See https://core.telegram.org/bots/api#maybeinaccessiblemessage
+type MaybeInaccessibleMessage interface{ Message | InaccessibleMessage }
+
+// MessageEntityType represents the type of a message entity.
+type MessageEntityType string
+
+const (
+	// 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"
+	// MessageEntityBlockquote identifies a blockquote entity.
+	MessageEntityBlockquote MessageEntityType = "blockquote"
+	// MessageEntityExpandableBlockquote identifies an expandable blockquote entity.
+	MessageEntityExpandableBlockquote MessageEntityType = "expandable_blockquote"
+	// 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"
+	// MessageEntityDateTime identifies a date-time entity.
+	MessageEntityDateTime MessageEntityType = "date_time"
+)
+
+// MessageEntity represents one special entity in a text message.
+// See https://core.telegram.org/bots/api#messageentity
+type MessageEntity struct {
+	Type MessageEntityType `json:"type"`
+
+	Offset        int    `json:"offset"`
+	Length        int    `json:"length"`
+	URL           string `json:"url,omitempty"`
+	User          *User  `json:"user,omitempty"`
+	Language      string `json:"language,omitempty"`
+	CustomEmojiID string `json:"custom_emoji_id,omitempty"`
+
+	UnixTime       int    `json:"unix_time,omitempty"`
+	DateTimeFormat string `json:"date_time_format,omitempty"`
+}
+
+// ReplyParameters describes the parameters to use when replying to a message.
+// See https://core.telegram.org/bots/api#replyparameters
+type ReplyParameters struct {
+	MessageID int   `json:"message_id"`
+	ChatID    int64 `json:"chat_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"`
+}
+
+// LinkPreviewOptions describes the options used for link preview generation.
+// See https://core.telegram.org/bots/api#linkpreviewoptions
+type LinkPreviewOptions struct {
+	IsDisabled       bool   `json:"is_disabled,omitempty"`
+	URL              string `json:"url,omitempty"`
+	PreferSmallMedia bool   `json:"prefer_small_media,omitempty"`
+	PreferLargeMedia bool   `json:"prefer_large_media,omitempty"`
+	ShowAboveText    bool   `json:"show_above_text,omitempty"`
+}
+
+// ReplyMarkup represents a custom keyboard or inline keyboard.
+// See https://core.telegram.org/bots/api#replymarkup
+type ReplyMarkup struct {
+	InlineKeyboard [][]InlineKeyboardButton `json:"inline_keyboard,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.
+// 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.
+// See https://core.telegram.org/bots/api#keyboardbutton
+type KeyboardButton struct {
+	Text              string                      `json:"text"`
+	IconCustomEmojiID string                      `json:"icon_custom_emoji_id,omitempty"`
+	Style             KeyboardButtonStyle         `json:"style,omitempty"`
+	RequestUsers      *KeyboardButtonRequestUsers `json:"request_users,omitempty"`
+	RequestChat       *KeyboardButtonRequestChat  `json:"request_chat,omitempty"`
+	RequestContact    bool                        `json:"request_contact,omitempty"`
+	RequestLocation   bool                        `json:"request_location,omitempty"`
+	RequestPoll       *KeyboardButtonPollType     `json:"request_poll,omitempty"`
+	WebApp            *WebAppInfo                 `json:"web_app,omitempty"`
+}
+
+// KeyboardButtonRequestUsers defines criteria used to request suitable users.
+// 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.
+// 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"`
+}
+
+// KeyboardButtonPollType represents the type of a poll that may be created from a keyboard button.
+// See https://core.telegram.org/bots/api#keyboardbuttonpolltype
+type KeyboardButtonPollType struct {
+	Type PollType `json:"type,omitempty"`
+}
+
+// InlineKeyboardButton represents one button of an inline keyboard.
+// 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"`
+}
+
+// ReplyKeyboardMarkup represents a custom keyboard with reply options.
+// See https://core.telegram.org/bots/api#replykeyboardmarkup
+type ReplyKeyboardMarkup struct {
+	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.
+// See https://core.telegram.org/bots/api#callbackquery
+type CallbackQuery struct {
+	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"`
+}
+
+// InputPollOption contains information about one answer option in a poll to be sent.
+// See https://core.telegram.org/bots/api#inputpolloption
+type InputPollOption struct {
+	Text          string          `json:"text"`
+	TextParseMode ParseMode       `json:"text_parse_mode,omitempty"`
+	TextEntities  []MessageEntity `json:"text_entities,omitempty"`
+}
+
+// PollType represents the type of a poll.
+type PollType string
+
+const (
+	// PollTypeRegular identifies a regular poll.
+	PollTypeRegular PollType = "regular"
+	// PollTypeQuiz identifies a quiz poll.
+	PollTypeQuiz PollType = "quiz"
+)
+
+// InputChecklistTask describes a task in a checklist.
+type InputChecklistTask struct {
+	ID           int             `json:"id"`
+	Text         string          `json:"text"`
+	ParseMode    ParseMode       `json:"parse_mode,omitempty"`
+	TextEntities []MessageEntity `json:"text_entities,omitempty"`
+}
+
+// InputChecklist represents a checklist to be sent.
+type InputChecklist struct {
+	Title                   string               `json:"title"`
+	ParseMode               ParseMode            `json:"parse_mode,omitempty"`
+	TitleEntities           []MessageEntity      `json:"title_entities,omitempty"`
+	Tasks                   []InputChecklistTask `json:"tasks"`
+	OtherCanAddTasks        bool                 `json:"other_can_add_tasks,omitempty"`
+	OtherCanMarkTasksAsDone bool                 `json:"other_can_mark_tasks_as_done,omitempty"`
+}
+
+// ChatActionType represents the type of chat action.
+type ChatActionType string
+
+const (
+	// 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 ChatActionType = ChatActionUploadVideoNote
+)
+
+// MessageReactionUpdated represents a change of a reaction on a message.
+// See https://core.telegram.org/bots/api#messagereactionupdated
+type MessageReactionUpdated struct {
+	Chat        *Chat          `json:"chat"`
+	MessageID   int            `json:"message_id"`
+	User        *User          `json:"user,omitempty"`
+	ActorChat   *Chat          `json:"actor_chat"`
+	Date        int            `json:"date"`
+	OldReaction []ReactionType `json:"old_reaction"`
+	NewReaction []ReactionType `json:"new_reaction"`
+}
+
+// MessageReactionCountUpdated represents a change in the count of reactions on a message.
+// 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.
+// See https://core.telegram.org/bots/api#reactiontype
+type ReactionType struct {
+	Type string `json:"type"`
+	// ReactionTypeEmoji
+	Emoji *string `json:"emoji,omitempty"`
+	// 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.
+// 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.
+type SuggestedPostPrice struct {
+	Currency string `json:"currency"`
+	Amount   int    `json:"amount"`
+}
+
+// SuggestedPostInfo contains information about a suggested post.
+// See https://core.telegram.org/bots/api#suggestedpostinfo
+type SuggestedPostInfo struct {
+	State    string             `json:"state"` // "pending", "approved", or "declined"
+	Price    SuggestedPostPrice `json:"price"`
+	SendDate int                `json:"send_date"`
+}
+
+// SuggestedPostParameters holds parameters for suggesting a post.
+type SuggestedPostParameters struct {
+	Price    SuggestedPostPrice `json:"price"`
+	SendDate int                `json:"send_date"`
+}

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

@@ -0,0 +1,240 @@
+package tgapi
+
+import (
+	"context"
+	"fmt"
+	"io"
+	"net/http"
+
+	"git.scuroneko.dev/scuroneko/laniakea/utils"
+)
+
+// 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,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)
+	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, EmptyParams]("getMe", NoParams)
+	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)
+	return req.Do(api)
+}
+
+// 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, EmptyParams]("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, EmptyParams]("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, EmptyParams]("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)
+}
+
+// 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)
+}
+
+// SetWebhookP holds parameters for the setWebhook method.
+// To upload a self-signed certificate, use Uploader.SetWebhook.
+// See https://core.telegram.org/bots/api#setwebhook
+type SetWebhookP struct {
+	URL                string       `json:"url"`
+	IPAddress          string       `json:"ip_address,omitempty"`
+	MaxConnections     int          `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 SetWebhookP) (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 SetWebhookP) (bool, error) {
+	req := NewRequest[bool]("setWebhook", params)
+	return req.DoWithContext(ctx, api)
+}
+
+// DeleteWebhookP holds parameters for the deleteWebhook method.
+// See https://core.telegram.org/bots/api#deletewebhook
+type DeleteWebhookP struct {
+	DropPendingUpdates bool `json:"drop_pending_updates,omitempty"`
+}
+
+// DeleteWebhook removes the current webhook integration.
+// Returns true on success.
+// See https://core.telegram.org/bots/api#deletewebhook
+func (api *API) DeleteWebhook(params DeleteWebhookP) (bool, error) {
+	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 DeleteWebhookP) (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)
+}
+
+// GetFileP holds parameters for the getFile method.
+// See https://core.telegram.org/bots/api#getfile
+type GetFileP 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 GetFileP) (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 GetFileP) (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,153 @@
+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"])
+	}
+}

tgapi/methods_types.go

@@ -0,0 +1,35 @@
+package tgapi
+
+// ParseMode represents the text formatting mode for message parsing.
+type ParseMode string
+
+const (
+	// ParseMDV2 enables MarkdownV2 style parsing.
+	ParseMDV2 ParseMode = "MarkdownV2"
+	// ParseHTML enables HTML style parsing.
+	ParseHTML ParseMode = "HTML"
+	// ParseMD enables legacy Markdown style parsing.
+	ParseMD 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{}
+
+// WebhookInfo describes the current webhook status.
+// See https://core.telegram.org/bots/api#webhookinfo
+type WebhookInfo struct {
+	URL                          string   `json:"url"`
+	HasCustomCertificate         bool     `json:"has_custom_certificate"`
+	PendingUpdateCount           int      `json:"pending_update_count"`
+	IPAddress                    string   `json:"ip_address,omitempty"`
+	LastErrorDate                int      `json:"last_error_date,omitempty"`
+	LastErrorMessage             string   `json:"last_error_message,omitempty"`
+	LastSynchronizationErrorDate int      `json:"last_synchronization_error_date,omitempty"`
+	MaxConnections               int      `json:"max_connections,omitempty"`
+	AllowedUpdates               []string `json:"allowed_updates,omitempty"`
+}

tgapi/parse_mode_test.go

@@ -0,0 +1,37 @@
+package tgapi
+
+import (
+	"encoding/json"
+	"strings"
+	"testing"
+)
+
+func TestParseNoneOmitsParseModeInJSON(t *testing.T) {
+	data, err := json.Marshal(SendMessageP{
+		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(SendMessageP{
+		ChatID:    42,
+		Text:      "hello",
+		ParseMode: ParseMDV2,
+	})
+	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,26 @@
+package tgapi
+
+import "context"
+
+// SetPassportDataErrorsP holds parameters for the setPassportDataErrors method.
+// See https://core.telegram.org/bots/api#setpassportdataerrors
+type SetPassportDataErrorsP struct {
+	UserID int64                  `json:"user_id"`
+	Errors []PassportElementError `json:"errors"`
+}
+
+// SetPassportDataErrors informs a user about Telegram Passport data errors.
+// Returns true on success.
+// See https://core.telegram.org/bots/api#setpassportdataerrors
+func (api *API) SetPassportDataErrors(params SetPassportDataErrorsP) (bool, error) {
+	req := NewRequest[bool]("setPassportDataErrors", params)
+	return req.Do(api)
+}
+
+// SetPassportDataErrorsWithContext is the context-aware variant of SetPassportDataErrors.
+// It executes the same request but uses ctx for cancellation and deadlines.
+// See https://core.telegram.org/bots/api#setpassportdataerrors
+func (api *API) SetPassportDataErrorsWithContext(ctx context.Context, params SetPassportDataErrorsP) (bool, error) {
+	req := NewRequest[bool]("setPassportDataErrors", params)
+	return req.DoWithContext(ctx, api)
+}

tgapi/passport_types.go

@@ -0,0 +1,5 @@
+package tgapi
+
+// PassportElementError is a JSON-serializable passport element error object.
+// See https://core.telegram.org/bots/api#passportelementerror
+type PassportElementError map[string]any

tgapi/payments_methods.go

@@ -0,0 +1,150 @@
+package tgapi
+
+import "context"
+
+// SendInvoiceP holds parameters for the sendInvoice method.
+// See https://core.telegram.org/bots/api#sendinvoice
+type SendInvoiceP 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.
+// See https://core.telegram.org/bots/api#sendinvoice
+func (api *API) SendInvoice(params SendInvoiceP) (Message, error) {
+	req := NewRequestWithChatID[Message]("sendInvoice", params, params.ChatID)
+	return req.Do(api)
+}
+
+// SendInvoiceWithContext is the context-aware variant of SendInvoice.
+// It executes the same request but uses ctx for cancellation and deadlines.
+// See https://core.telegram.org/bots/api#sendinvoice
+func (api *API) SendInvoiceWithContext(ctx context.Context, params SendInvoiceP) (Message, error) {
+	req := NewRequestWithChatID[Message]("sendInvoice", params, params.ChatID)
+	return req.DoWithContext(ctx, api)
+}
+
+// CreateInvoiceLinkP holds parameters for the createInvoiceLink method.
+// See https://core.telegram.org/bots/api#createinvoicelink
+type CreateInvoiceLinkP 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.
+// See https://core.telegram.org/bots/api#createinvoicelink
+func (api *API) CreateInvoiceLink(params CreateInvoiceLinkP) (string, error) {
+	req := NewRequest[string]("createInvoiceLink", params)
+	return req.Do(api)
+}
+
+// CreateInvoiceLinkWithContext is the context-aware variant of CreateInvoiceLink.
+// It executes the same request but uses ctx for cancellation and deadlines.
+// See https://core.telegram.org/bots/api#createinvoicelink
+func (api *API) CreateInvoiceLinkWithContext(ctx context.Context, params CreateInvoiceLinkP) (string, error) {
+	req := NewRequest[string]("createInvoiceLink", params)
+	return req.DoWithContext(ctx, api)
+}
+
+// AnswerShippingQueryP holds parameters for the answerShippingQuery method.
+// See https://core.telegram.org/bots/api#answershippingquery
+type AnswerShippingQueryP 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.
+// Returns true on success.
+// See https://core.telegram.org/bots/api#answershippingquery
+func (api *API) AnswerShippingQuery(params AnswerShippingQueryP) (bool, error) {
+	req := NewRequest[bool]("answerShippingQuery", params)
+	return req.Do(api)
+}
+
+// AnswerShippingQueryWithContext is the context-aware variant of AnswerShippingQuery.
+// It executes the same request but uses ctx for cancellation and deadlines.
+// See https://core.telegram.org/bots/api#answershippingquery
+func (api *API) AnswerShippingQueryWithContext(ctx context.Context, params AnswerShippingQueryP) (bool, error) {
+	req := NewRequest[bool]("answerShippingQuery", params)
+	return req.DoWithContext(ctx, api)
+}
+
+// AnswerPreCheckoutQueryP holds parameters for the answerPreCheckoutQuery method.
+// See https://core.telegram.org/bots/api#answerprecheckoutquery
+type AnswerPreCheckoutQueryP struct {
+	PreCheckoutQueryID string `json:"pre_checkout_query_id"`
+	OK                 bool   `json:"ok"`
+	ErrorMessage       string `json:"error_message,omitempty"`
+}
+
+// AnswerPreCheckoutQuery answers a pre-checkout query.
+// Returns true on success.
+// See https://core.telegram.org/bots/api#answerprecheckoutquery
+func (api *API) AnswerPreCheckoutQuery(params AnswerPreCheckoutQueryP) (bool, error) {
+	req := NewRequest[bool]("answerPreCheckoutQuery", params)
+	return req.Do(api)
+}
+
+// AnswerPreCheckoutQueryWithContext is the context-aware variant of AnswerPreCheckoutQuery.
+// It executes the same request but uses ctx for cancellation and deadlines.
+// See https://core.telegram.org/bots/api#answerprecheckoutquery
+func (api *API) AnswerPreCheckoutQueryWithContext(ctx context.Context, params AnswerPreCheckoutQueryP) (bool, error) {
+	req := NewRequest[bool]("answerPreCheckoutQuery", params)
+	return req.DoWithContext(ctx, api)
+}

tgapi/payments_types.go

@@ -0,0 +1,16 @@
+package tgapi
+
+// LabeledPrice represents a price portion.
+// See https://core.telegram.org/bots/api#labeledprice
+type LabeledPrice struct {
+	Label  string `json:"label"`
+	Amount int    `json:"amount"`
+}
+
+// ShippingOption represents one shipping option.
+// See https://core.telegram.org/bots/api#shippingoption
+type ShippingOption struct {
+	ID     string         `json:"id"`
+	Title  string         `json:"title"`
+	Prices []LabeledPrice `json:"prices"`
+}

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/stars_methods.go

@@ -0,0 +1,87 @@
+package tgapi
+
+import "context"
+
+// GetStarTransactionsP holds parameters for the getStarTransactions method.
+// See https://core.telegram.org/bots/api#getstartransactions
+type GetStarTransactionsP struct {
+	Offset int `json:"offset,omitempty"`
+	Limit  int `json:"limit,omitempty"`
+}
+
+// GetMyStarBalance returns the bot's Telegram Star balance.
+// 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.
+// 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.
+// See https://core.telegram.org/bots/api#getstartransactions
+func (api *API) GetStarTransactions(params GetStarTransactionsP) (StarTransactions, error) {
+	req := NewRequest[StarTransactions]("getStarTransactions", params)
+	return req.Do(api)
+}
+
+// GetStarTransactionsWithContext is the context-aware variant of GetStarTransactions.
+// It executes the same request but uses ctx for cancellation and deadlines.
+// See https://core.telegram.org/bots/api#getstartransactions
+func (api *API) GetStarTransactionsWithContext(ctx context.Context, params GetStarTransactionsP) (StarTransactions, error) {
+	req := NewRequest[StarTransactions]("getStarTransactions", params)
+	return req.DoWithContext(ctx, api)
+}
+
+// RefundStarPaymentP holds parameters for the refundStarPayment method.
+// See https://core.telegram.org/bots/api#refundstarpayment
+type RefundStarPaymentP struct {
+	UserID                  int64  `json:"user_id"`
+	TelegramPaymentChargeID string `json:"telegram_payment_charge_id"`
+}
+
+// RefundStarPayment refunds a successful Telegram Stars payment.
+// Returns true on success.
+// See https://core.telegram.org/bots/api#refundstarpayment
+func (api *API) RefundStarPayment(params RefundStarPaymentP) (bool, error) {
+	req := NewRequest[bool]("refundStarPayment", params)
+	return req.Do(api)
+}
+
+// RefundStarPaymentWithContext is the context-aware variant of RefundStarPayment.
+// It executes the same request but uses ctx for cancellation and deadlines.
+// See https://core.telegram.org/bots/api#refundstarpayment
+func (api *API) RefundStarPaymentWithContext(ctx context.Context, params RefundStarPaymentP) (bool, error) {
+	req := NewRequest[bool]("refundStarPayment", params)
+	return req.DoWithContext(ctx, api)
+}
+
+// EditUserStarSubscriptionP holds parameters for the editUserStarSubscription method.
+// See https://core.telegram.org/bots/api#edituserstarsubscription
+type EditUserStarSubscriptionP 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.
+// Returns true on success.
+// See https://core.telegram.org/bots/api#edituserstarsubscription
+func (api *API) EditUserStarSubscription(params EditUserStarSubscriptionP) (bool, error) {
+	req := NewRequest[bool]("editUserStarSubscription", params)
+	return req.Do(api)
+}
+
+// EditUserStarSubscriptionWithContext is the context-aware variant of EditUserStarSubscription.
+// It executes the same request but uses ctx for cancellation and deadlines.
+// See https://core.telegram.org/bots/api#edituserstarsubscription
+func (api *API) EditUserStarSubscriptionWithContext(ctx context.Context, params EditUserStarSubscriptionP) (bool, error) {
+	req := NewRequest[bool]("editUserStarSubscription", params)
+	return req.DoWithContext(ctx, api)
+}

tgapi/stars_types.go

@@ -0,0 +1,18 @@
+package tgapi
+
+// StarTransaction describes a Telegram Star transaction.
+// 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.
+// See https://core.telegram.org/bots/api#startransactions
+type StarTransactions struct {
+	Transactions []StarTransaction `json:"transactions"`
+}

tgapi/stickers_methods.go

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

tgapi/stickers_types.go

@@ -0,0 +1,88 @@
+package tgapi
+
+// MaskPositionPoint represents the part of the face where a mask should be placed.
+type MaskPositionPoint string
+
+const (
+	// MaskPositionForehead places the mask on the forehead.
+	MaskPositionForehead MaskPositionPoint = "forehead"
+	// MaskPositionEyes places the mask on the eyes.
+	MaskPositionEyes MaskPositionPoint = "eyes"
+	// MaskPositionMouth places the mask on the mouth.
+	MaskPositionMouth MaskPositionPoint = "mouth"
+	// MaskPositionChin places the mask on the chin.
+	MaskPositionChin MaskPositionPoint = "chin"
+)
+
+// MaskPosition describes the position on faces where a mask should be placed by default.
+// See https://core.telegram.org/bots/api#maskposition
+type MaskPosition struct {
+	Point  MaskPositionPoint `json:"point"`
+	XShift float32           `json:"x_shift"`
+	YShift float32           `json:"y_shift"`
+	Scale  float32           `json:"scale"`
+}
+
+// StickerType represents the type of a sticker.
+type StickerType string
+
+const (
+	// StickerTypeRegular is a regular sticker.
+	StickerTypeRegular StickerType = "regular"
+	// StickerTypeMask is a mask sticker that can be placed on faces.
+	StickerTypeMask StickerType = "mask"
+	// StickerTypeCustomEmoji is a custom emoji sticker.
+	StickerTypeCustomEmoji StickerType = "custom_emoji"
+)
+
+// Sticker represents a sticker.
+// See https://core.telegram.org/bots/api#sticker
+type Sticker struct {
+	FileId       string      `json:"file_id"`
+	FileUniqueId string      `json:"file_unique_id"`
+	Type         StickerType `json:"type"`
+	Width        int         `json:"width"`
+	Height       int         `json:"height"`
+	IsAnimated   bool        `json:"is_animated"`
+	IsVideo      bool        `json:"is_video"`
+
+	Thumbnail      *PhotoSize    `json:"thumbnail,omitempty"`
+	Emoji          *string       `json:"emoji,omitempty"`
+	SetName        *string       `json:"set_name,omitempty"`
+	MaskPosition   *MaskPosition `json:"mask_position,omitempty"`
+	CustomEmojiID  *string       `json:"custom_emoji_id,omitempty"`
+	NeedRepainting *bool         `json:"need_repainting,omitempty"`
+	FileSize       *int64        `json:"file_size,omitempty"`
+}
+
+// StickerSet represents a sticker set.
+// See https://core.telegram.org/bots/api#stickerset
+type StickerSet struct {
+	Name        string      `json:"name"`
+	Title       string      `json:"title"`
+	StickerType StickerType `json:"sticker_type"`
+	Stickers    []Sticker   `json:"stickers"`
+	Thumbnail   *PhotoSize  `json:"thumbnail,omitempty"`
+}
+
+// InputStickerFormat represents the format of an input sticker.
+type InputStickerFormat string
+
+const (
+	// InputStickerFormatStatic is a static sticker (WEBP).
+	InputStickerFormatStatic InputStickerFormat = "static"
+	// InputStickerFormatAnimated is an animated sticker (TGS).
+	InputStickerFormatAnimated InputStickerFormat = "animated"
+	// InputStickerFormatVideo is a video sticker (WEBM).
+	InputStickerFormatVideo InputStickerFormat = "video"
+)
+
+// InputSticker describes a sticker to be added to a sticker set.
+// See https://core.telegram.org/bots/api#inputsticker
+type InputSticker struct {
+	Sticker      string             `json:"sticker"`
+	Format       InputStickerFormat `json:"format"`
+	EmojiList    []string           `json:"emoji_list"`
+	MaskPosition *MaskPosition      `json:"mask_position,omitempty"`
+	Keywords     []string           `json:"keywords,omitempty"`
+}

tgapi/types.go

@@ -0,0 +1,456 @@
+package tgapi
+
+import "encoding/json"
+
+// UpdateType represents the type of incoming update.
+type UpdateType string
+
+const (
+	// UpdateTypeUnknown marks an update whose payload does not match a known Telegram update kind.
+	UpdateTypeUnknown UpdateType = "unknown"
+
+	// UpdateTypeMessage is a regular message update.
+	UpdateTypeMessage UpdateType = "message"
+	// UpdateTypeEditedMessage is an edited message update.
+	UpdateTypeEditedMessage UpdateType = "edited_message"
+	// UpdateTypeChannelPost is a channel post update.
+	UpdateTypeChannelPost UpdateType = "channel_post"
+	// UpdateTypeEditedChannelPost is an edited channel post update.
+	UpdateTypeEditedChannelPost UpdateType = "edited_channel_post"
+	// UpdateTypeMessageReaction is a message reaction update.
+	UpdateTypeMessageReaction UpdateType = "message_reaction"
+	// UpdateTypeMessageReactionCount is a message reaction count update.
+	UpdateTypeMessageReactionCount UpdateType = "message_reaction_count"
+
+	// UpdateTypeBusinessConnection is a business connection update.
+	UpdateTypeBusinessConnection UpdateType = "business_connection"
+	// UpdateTypeBusinessMessage is a business message update.
+	UpdateTypeBusinessMessage UpdateType = "business_message"
+	// UpdateTypeEditedBusinessMessage is an edited business message update.
+	UpdateTypeEditedBusinessMessage UpdateType = "edited_business_message"
+	// UpdateTypeDeletedBusinessMessages is a deleted business messages update.
+	UpdateTypeDeletedBusinessMessages UpdateType = "deleted_business_messages"
+
+	// UpdateTypeInlineQuery is an inline query update.
+	UpdateTypeInlineQuery UpdateType = "inline_query"
+	// UpdateTypeChosenInlineResult is a chosen inline result update.
+	UpdateTypeChosenInlineResult UpdateType = "chosen_inline_result"
+	// UpdateTypeCallbackQuery is a callback query update.
+	UpdateTypeCallbackQuery UpdateType = "callback_query"
+	// UpdateTypeShippingQuery is a shipping query update.
+	UpdateTypeShippingQuery UpdateType = "shipping_query"
+	// UpdateTypePreCheckoutQuery is a pre-checkout query update.
+	UpdateTypePreCheckoutQuery UpdateType = "pre_checkout_query"
+	// UpdateTypePurchasedPaidMedia is a purchased paid media update.
+	UpdateTypePurchasedPaidMedia UpdateType = "purchased_paid_media"
+	// UpdateTypePoll is a poll update.
+	UpdateTypePoll UpdateType = "poll"
+	// UpdateTypePollAnswer is a poll answer update.
+	UpdateTypePollAnswer UpdateType = "poll_answer"
+	// UpdateTypeMyChatMember is a my chat member update.
+	UpdateTypeMyChatMember UpdateType = "my_chat_member"
+	// UpdateTypeChatMember is a chat member update.
+	UpdateTypeChatMember UpdateType = "chat_member"
+	// UpdateTypeChatJoinRequest is a chat join request update.
+	UpdateTypeChatJoinRequest UpdateType = "chat_join_request"
+	// UpdateTypeChatBoost is a chat boost update.
+	UpdateTypeChatBoost UpdateType = "chat_boost"
+	// UpdateTypeRemovedChatBoost is a removed chat boost update.
+	UpdateTypeRemovedChatBoost UpdateType = "removed_chat_boost"
+)
+
+// Update represents an incoming update from Telegram.
+// See https://core.telegram.org/bots/api#update
+type Update struct {
+	Type UpdateType `json:"-"`
+
+	UpdateID          int      `json:"update_id"`
+	Message           *Message `json:"message,omitempty"`
+	EditedMessage     *Message `json:"edited_message,omitempty"`
+	ChannelPost       *Message `json:"channel_post,omitempty"`
+	EditedChannelPost *Message `json:"edited_channel_post,omitempty"`
+
+	BusinessConnection      *BusinessConnection          `json:"business_connection,omitempty"`
+	BusinessMessage         *Message                     `json:"business_message,omitempty"`
+	EditedBusinessMessage   *Message                     `json:"edited_business_message,omitempty"`
+	DeletedBusinessMessages *BusinessMessagesDeleted     `json:"deleted_business_messages,omitempty"`
+	MessageReaction         *MessageReactionUpdated      `json:"message_reaction,omitempty"`
+	MessageReactionCount    *MessageReactionCountUpdated `json:"message_reaction_count,omitempty"`
+
+	InlineQuery        *InlineQuery        `json:"inline_query,omitempty"`
+	ChosenInlineResult *ChosenInlineResult `json:"chosen_inline_result,omitempty"`
+	CallbackQuery      *CallbackQuery      `json:"callback_query,omitempty"`
+	ShippingQuery      *ShippingQuery      `json:"shipping_query,omitempty"`
+	PreCheckoutQuery   *PreCheckoutQuery   `json:"pre_checkout_query,omitempty"`
+	PurchasedPaidMedia *PaidMediaPurchased `json:"purchased_paid_media,omitempty"`
+
+	Poll             *Poll              `json:"poll,omitempty"`
+	PollAnswer       *PollAnswer        `json:"poll_answer,omitempty"`
+	MyChatMember     *ChatMemberUpdated `json:"my_chat_member,omitempty"`
+	ChatMember       *ChatMemberUpdated `json:"chat_member,omitempty"`
+	ChatJoinRequest  *ChatJoinRequest   `json:"chat_join_request,omitempty"`
+	ChatBoost        *ChatBoostUpdated  `json:"chat_boost,omitempty"`
+	RemovedChatBoost *ChatBoostRemoved  `json:"removed_chat_boost,omitempty"`
+}
+
+// UnmarshalJSON decodes an update and derives its Type from the populated payload field.
+func (u *Update) UnmarshalJSON(data []byte) error {
+	type Alias Update
+
+	var aux Alias
+	if err := json.Unmarshal(data, &aux); err != nil {
+		return err
+	}
+
+	*u = Update(aux)
+
+	switch {
+	case u.Message != nil:
+		u.Type = UpdateTypeMessage
+	case u.EditedMessage != nil:
+		u.Type = UpdateTypeEditedMessage
+	case u.ChannelPost != nil:
+		u.Type = UpdateTypeChannelPost
+	case u.EditedChannelPost != nil:
+		u.Type = UpdateTypeEditedChannelPost
+
+	case u.BusinessConnection != nil:
+		u.Type = UpdateTypeBusinessConnection
+	case u.BusinessMessage != nil:
+		u.Type = UpdateTypeBusinessMessage
+	case u.EditedBusinessMessage != nil:
+		u.Type = UpdateTypeEditedBusinessMessage
+	case u.DeletedBusinessMessages != nil:
+		u.Type = UpdateTypeDeletedBusinessMessages
+	case u.MessageReaction != nil:
+		u.Type = UpdateTypeMessageReaction
+	case u.MessageReactionCount != nil:
+		u.Type = UpdateTypeMessageReactionCount
+
+	case u.InlineQuery != nil:
+		u.Type = UpdateTypeInlineQuery
+	case u.ChosenInlineResult != nil:
+		u.Type = UpdateTypeChosenInlineResult
+	case u.CallbackQuery != nil:
+		u.Type = UpdateTypeCallbackQuery
+	case u.ShippingQuery != nil:
+		u.Type = UpdateTypeShippingQuery
+	case u.PreCheckoutQuery != nil:
+		u.Type = UpdateTypePreCheckoutQuery
+	case u.PurchasedPaidMedia != nil:
+		u.Type = UpdateTypePurchasedPaidMedia
+
+	case u.Poll != nil:
+		u.Type = UpdateTypePoll
+	case u.PollAnswer != nil:
+		u.Type = UpdateTypePollAnswer
+	case u.MyChatMember != nil:
+		u.Type = UpdateTypeMyChatMember
+	case u.ChatMember != nil:
+		u.Type = UpdateTypeChatMember
+	case u.ChatJoinRequest != nil:
+		u.Type = UpdateTypeChatJoinRequest
+	case u.ChatBoost != nil:
+		u.Type = UpdateTypeChatBoost
+	case u.RemovedChatBoost != nil:
+		u.Type = UpdateTypeRemovedChatBoost
+	default:
+		u.Type = UpdateTypeUnknown
+	}
+
+	return nil
+}
+
+// InlineQuery represents an incoming inline query.
+// See https://core.telegram.org/bots/api#inlinequery
+type InlineQuery struct {
+	ID       string    `json:"id"`
+	From     User      `json:"from"`
+	Query    string    `json:"query"`
+	Offset   string    `json:"offset"`
+	ChatType *ChatType `json:"chat_type,omitempty"`
+	Location *Location `json:"location,omitempty"`
+}
+
+// ChosenInlineResult represents a result of an inline query that was chosen by the user.
+// See https://core.telegram.org/bots/api#choseninlineresult
+type ChosenInlineResult struct {
+	ResultID        string    `json:"result_id"`
+	From            User      `json:"from"`
+	Location        *Location `json:"location,omitempty"`
+	InlineMessageID string    `json:"inline_message_id"`
+	Query           string    `json:"query"`
+}
+
+// ShippingQuery represents an incoming shipping query.
+// See https://core.telegram.org/bots/api#shippingquery
+type ShippingQuery struct {
+	ID              string          `json:"id"`
+	From            User            `json:"from"`
+	InvoicePayload  string          `json:"invoice_payload"`
+	ShippingAddress ShippingAddress `json:"shipping_address"`
+}
+
+// ShippingAddress represents a shipping address.
+// See https://core.telegram.org/bots/api#shippingaddress
+type ShippingAddress struct {
+	CountryCode string `json:"country_code"`
+	State       string `json:"state"`
+	City        string `json:"city"`
+	StreetLine1 string `json:"street_line1"`
+	StreetLine2 string `json:"street_line2"`
+	PostCode    string `json:"post_code"`
+}
+
+// OrderInfo represents information about an order.
+// See https://core.telegram.org/bots/api#orderinfo
+type OrderInfo struct {
+	Name            string          `json:"name"`
+	PhoneNumber     string          `json:"phone_number"`
+	Email           string          `json:"email"`
+	ShippingAddress ShippingAddress `json:"shipping_address"`
+}
+
+// PreCheckoutQuery represents an incoming pre-checkout query.
+// See https://core.telegram.org/bots/api#precheckoutquery
+type PreCheckoutQuery struct {
+	ID               string     `json:"id"`
+	From             User       `json:"from"`
+	Currency         string     `json:"currency"`
+	TotalAmount      int        `json:"total_amount"`
+	InvoicePayload   string     `json:"invoice_payload"`
+	ShippingOptionID string     `json:"shipping_option_id"`
+	OrderInfo        *OrderInfo `json:"order_info,omitempty"`
+}
+
+// PaidMediaPurchased represents a purchased paid media.
+// See https://core.telegram.org/bots/api#paidmediapurchased
+type PaidMediaPurchased struct {
+	From             User   `json:"from"`
+	PaidMediaPayload string `json:"paid_media_payload"`
+}
+
+// File represents a file ready to be downloaded.
+// See https://core.telegram.org/bots/api#file
+type File struct {
+	FileId       string `json:"file_id"`
+	FileUniqueID string `json:"file_unique_id"`
+	FileSize     int64  `json:"file_size,omitempty"`
+	FilePath     string `json:"file_path,omitempty"`
+}
+
+// Audio represents an audio file to be treated as music by the Telegram clients.
+// See https://core.telegram.org/bots/api#audio
+type Audio struct {
+	FileID       string `json:"file_id"`
+	FileUniqueID string `json:"file_unique_id"`
+	Duration     int    `json:"duration"`
+
+	Performer string     `json:"performer,omitempty"`
+	Title     string     `json:"title,omitempty"`
+	FileName  string     `json:"file_name,omitempty"`
+	MimeType  string     `json:"mime_type,omitempty"`
+	FileSize  int64      `json:"file_size,omitempty"`
+	Thumbnail *PhotoSize `json:"thumbnail,omitempty"`
+}
+
+// PollOption contains information about one answer option in a poll.
+// See https://core.telegram.org/bots/api#polloption
+type PollOption struct {
+	Text         string          `json:"text"`
+	TextEntities []MessageEntity `json:"text_entities"`
+	VoterCount   int             `json:"voter_count"`
+}
+
+// Poll contains information about a poll.
+// See https://core.telegram.org/bots/api#poll
+type Poll struct {
+	ID               string          `json:"id"`
+	Question         string          `json:"question"`
+	QuestionEntities []MessageEntity `json:"question_entities"`
+	Options          []PollOption    `json:"options"`
+	TotalVoterCount  int             `json:"total_voter_count"`
+	IsClosed         bool            `json:"is_closed"`
+	IsAnonymous      bool            `json:"is_anonymous"`
+	Type             PollType        `json:"type"`
+
+	AllowsMultipleAnswers bool            `json:"allows_multiple_answers"`
+	CorrectOptionID       *int            `json:"correct_option_id,omitempty"`
+	Explanation           *string         `json:"explanation,omitempty"`
+	ExplanationEntities   []MessageEntity `json:"explanation_entities,omitempty"`
+	OpenPeriod            int             `json:"open_period,omitempty"`
+	CloseDate             int             `json:"close_date,omitempty"`
+}
+
+// PollAnswer represents an answer of a user in a poll.
+// See https://core.telegram.org/bots/api#pollanswer
+type PollAnswer struct {
+	PollID    string `json:"poll_id"`
+	VoterChat Chat   `json:"voter_chat"`
+	User      User   `json:"user"`
+	OptionIDS []int  `json:"option_ids"`
+}
+
+// ChatMemberUpdated represents changes in the status of a chat member.
+// See https://core.telegram.org/bots/api#chatmemberupdated
+type ChatMemberUpdated struct {
+	Chat                    Chat            `json:"chat"`
+	From                    User            `json:"from"`
+	Date                    int64           `json:"date"`
+	OldChatMember           ChatMember      `json:"old_chat_member"`
+	NewChatMember           ChatMember      `json:"new_chat_member"`
+	InviteLink              *ChatInviteLink `json:"invite_link,omitempty"`
+	ViaJoinRequest          *bool           `json:"via_join_request,omitempty"`
+	ViaChatFolderInviteLink *bool           `json:"via_chat_folder_invite_link,omitempty"`
+}
+
+// ChatJoinRequest represents a join request sent to a chat.
+// See https://core.telegram.org/bots/api#chatjoinrequest
+type ChatJoinRequest struct {
+	Chat       Chat            `json:"chat"`
+	From       User            `json:"from"`
+	UserChatID int64           `json:"user_chat_id"`
+	Date       int64           `json:"date"`
+	Bio        *string         `json:"bio,omitempty"`
+	InviteLink *ChatInviteLink `json:"invite_link,omitempty"`
+}
+
+// Location represents a point on the map.
+// See https://core.telegram.org/bots/api#location
+type Location struct {
+	Latitude             float64 `json:"latitude"`
+	Longitude            float64 `json:"longitude"`
+	HorizontalAccuracy   float64 `json:"horizontal_accuracy"`
+	LivePeriod           int     `json:"live_period"`
+	Heading              int     `json:"heading"`
+	ProximityAlertRadius int     `json:"proximity_alert_radius"`
+}
+
+// LocationAddress represents a human-readable address of a location.
+type LocationAddress struct {
+	CountryCode string  `json:"country_code"`
+	State       *string `json:"state,omitempty"`
+	City        *string `json:"city,omitempty"`
+	Street      *string `json:"street,omitempty"`
+}
+
+// Venue represents a venue.
+// See https://core.telegram.org/bots/api#venue
+type Venue struct {
+	Location        Location `json:"location"`
+	Title           string   `json:"title"`
+	Address         string   `json:"address"`
+	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"`
+}
+
+// WebAppInfo contains information about a Web App.
+// See https://core.telegram.org/bots/api#webappinfo
+type WebAppInfo struct {
+	URL string `json:"url"`
+}
+
+// StarAmount represents an amount of Telegram Stars.
+type StarAmount struct {
+	Amount         int `json:"amount"`
+	NanostarAmount int `json:"nanostar_amount"`
+}
+
+// Story represents a story.
+type Story struct {
+	Chat Chat `json:"chat"`
+	ID   int  `json:"id"`
+}
+
+// AcceptedGiftTypes represents the types of gifts accepted by a user or chat.
+type AcceptedGiftTypes struct {
+	UnlimitedGifts      bool `json:"unlimited_gifts"`
+	LimitedGifts        bool `json:"limited_gifts"`
+	UniqueGifts         bool `json:"unique_gifts"`
+	PremiumSubscription bool `json:"premium_subscription"`
+	GiftsFromChannels   bool `json:"gifts_from_channels"`
+}
+
+// UniqueGiftColors represents color information for a unique gift.
+type UniqueGiftColors struct {
+	ModelCustomEmojiID    string `json:"model_custom_emoji_id"`
+	SymbolCustomEmojiID   string `json:"symbol_custom_emoji_id"`
+	LightThemeMainColor   int    `json:"light_theme_main_color"`
+	LightThemeOtherColors []int  `json:"light_theme_other_colors"`
+	DarkThemeMainColor    int    `json:"dark_theme_main_color"`
+	DarkThemeOtherColors  []int  `json:"dark_theme_other_colors"`
+}
+
+// GiftBackground represents the background of a gift.
+type GiftBackground struct {
+	CenterColor int `json:"center_color"`
+	EdgeColor   int `json:"edge_color"`
+	TextColor   int `json:"text_color"`
+}
+
+// Gift represents a gift that can be sent.
+type Gift struct {
+	ID                     string          `json:"id"`
+	Sticker                Sticker         `json:"sticker"`
+	StarCount              int             `json:"star_count"`
+	UpdateStarCount        *int            `json:"update_star_count,omitempty"`
+	IsPremium              *bool           `json:"is_premium,omitempty"`
+	HasColors              *bool           `json:"has_colors,omitempty"`
+	TotalCount             *int            `json:"total_count,omitempty"`
+	RemainingCount         *int            `json:"remaining_count,omitempty"`
+	PersonalTotalCount     *int            `json:"personal_total_count,omitempty"`
+	PersonalRemainingCount *int            `json:"personal_remaining_count,omitempty"`
+	Background             *GiftBackground `json:"background,omitempty"`
+	UniqueGiftVariantColor *int            `json:"unique_gift_variant_color,omitempty"`
+	PublisherChat          *Chat           `json:"publisher_chat,omitempty"`
+}
+
+// Gifts represents a list of gifts.
+type Gifts struct {
+	Gifts []Gift `json:"gifts"`
+}
+
+// OwnedGiftType represents the type of an owned gift.
+type OwnedGiftType string
+
+const (
+	// OwnedGiftRegularType identifies a regular owned gift.
+	OwnedGiftRegularType OwnedGiftType = "regular"
+	// OwnedGiftUniqueType identifies a unique owned gift.
+	OwnedGiftUniqueType OwnedGiftType = "unique"
+)
+
+// OwnedGift represents a gift owned by a user or chat.
+type OwnedGift struct {
+	Type        OwnedGiftType `json:"type"`
+	OwnerGiftID *string       `json:"owner_gift_id,omitempty"`
+	SendDate    *int          `json:"send_date,omitempty"`
+	IsSaved     *bool         `json:"is_saved,omitempty"`
+
+	// Fields specific to "regular" type
+	Gift                    Gift            `json:"gift"`
+	SenderUser              *User           `json:"sender_user,omitempty"`
+	Text                    string          `json:"text,omitempty"`
+	Entities                []MessageEntity `json:"entities,omitempty"`
+	IsPrivate               *bool           `json:"is_private,omitempty"`
+	CanBeUpgraded           *bool           `json:"can_be_upgraded,omitempty"`
+	WasRefunded             *bool           `json:"was_refunded,omitempty"`
+	ConvertStarCount        *int            `json:"convert_star_count,omitempty"`
+	PrepaidUpgradeStarCount *int            `json:"prepaid_upgrade_star_count,omitempty"`
+	IsUpgradeSeparate       *bool           `json:"is_upgrade_separate,omitempty"`
+	UniqueGiftNumber        *int            `json:"unique_gift_number,omitempty"`
+
+	// Fields specific to "unique" type
+	CanBeTransferred  *bool `json:"can_be_transferred,omitempty"`
+	TransferStarCount *int  `json:"transfer_star_count,omitempty"`
+	NextTransferDate  *int  `json:"next_transfer_date,omitempty"`
+}
+
+// OwnedGifts represents a list of owned gifts with pagination.
+type OwnedGifts struct {
+	TotalCount int         `json:"total_count"`
+	Gifts      []OwnedGift `json:"gifts"`
+	NextOffset string      `json:"next_offset"`
+}

tgapi/types_test.go

@@ -0,0 +1,116 @@
+package tgapi
+
+import (
+	"encoding/json"
+	"strings"
+	"testing"
+)
+
+func TestUpdateUnmarshalSetsType(t *testing.T) {
+	tests := []struct {
+		name string
+		body string
+		want UpdateType
+	}{
+		{
+			name: "deleted business messages",
+			body: `{
+				"update_id": 1,
+				"deleted_business_messages": {
+					"business_connection_id": "conn",
+					"chat": {"id": 42, "type": "private"},
+					"message_ids": [3, 5]
+				}
+			}`,
+			want: UpdateTypeDeletedBusinessMessages,
+		},
+		{
+			name: "callback query",
+			body: `{
+				"update_id": 2,
+				"callback_query": {
+					"id": "cb",
+					"from": {"id": 1, "is_bot": false, "first_name": "Test"},
+					"chat_instance": "instance",
+					"data": "payload"
+				}
+			}`,
+			want: UpdateTypeCallbackQuery,
+		},
+		{
+			name: "chat boost",
+			body: `{
+				"update_id": 3,
+				"chat_boost": {
+					"chat": {"id": -1001, "type": "supergroup", "title": "Boosted"},
+					"boost": {
+						"boost_id": "boost-1",
+						"add_date": 1735689600,
+						"expiration_date": 1738291600,
+						"source": {
+							"source": "premium",
+							"user": {"id": 1, "is_bot": false, "first_name": "Test"}
+						}
+					}
+				}
+			}`,
+			want: UpdateTypeChatBoost,
+		},
+		{
+			name: "unknown",
+			body: `{"update_id":4}`,
+			want: UpdateTypeUnknown,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			var update Update
+			if err := json.Unmarshal([]byte(tt.body), &update); err != nil {
+				t.Fatalf("Unmarshal returned error: %v", err)
+			}
+			if update.Type != tt.want {
+				t.Fatalf("unexpected update type: got %q want %q", update.Type, tt.want)
+			}
+			if tt.want == UpdateTypeChatBoost && update.ChatBoost.Boost.BoostID != "boost-1" {
+				t.Fatalf("unexpected boost id: got %q want %q", update.ChatBoost.Boost.BoostID, "boost-1")
+			}
+		})
+	}
+}
+
+func TestUpdateMarshalOmitsSyntheticTypeField(t *testing.T) {
+	update := Update{
+		UpdateID: 1,
+		Type:     UpdateTypeCallbackQuery,
+		CallbackQuery: &CallbackQuery{
+			ID:           "cb",
+			From:         User{ID: 1, FirstName: "Test"},
+			ChatInstance: "instance",
+			Data:         "payload",
+		},
+	}
+
+	data, err := json.Marshal(update)
+	if err != nil {
+		t.Fatalf("Marshal returned error: %v", err)
+	}
+
+	got := string(data)
+	if strings.Contains(got, `"type"`) {
+		t.Fatalf("unexpected synthetic type field, got %s", got)
+	}
+}
+
+func TestUpdateShippingQueryIsNilWhenAbsent(t *testing.T) {
+	var update Update
+	if err := json.Unmarshal([]byte(`{"update_id":1}`), &update); err != nil {
+		t.Fatalf("Unmarshal returned error: %v", err)
+	}
+	if update.ShippingQuery != nil {
+		t.Fatalf("expected ShippingQuery to be nil, got %+v", update.ShippingQuery)
+	}
+	if update.Type != UpdateTypeUnknown {
+		t.Fatalf("expected UpdateTypeUnknown, got %q", update.Type)
+	}
+}

tgapi/uploader_api.go

@@ -0,0 +1,261 @@
+package tgapi
+
+import (
+	"bytes"
+	"context"
+	"fmt"
+	"mime/multipart"
+	"net/http"
+	"path/filepath"
+	"strings"
+	"time"
+
+	"git.scuroneko.dev/scuroneko/laniakea/utils"
+	"git.scuroneko.dev/scuroneko/slog"
+)
+
+const (
+	// UploaderPhotoType is the multipart field name for photo uploads.
+	UploaderPhotoType UploaderFileType = "photo"
+	// UploaderVideoType is the multipart field name for video uploads.
+	UploaderVideoType UploaderFileType = "video"
+	// UploaderAudioType is the multipart field name for audio uploads.
+	UploaderAudioType UploaderFileType = "audio"
+	// UploaderDocumentType is the multipart field name for document uploads.
+	UploaderDocumentType UploaderFileType = "document"
+	// UploaderVoiceType is the multipart field name for voice uploads.
+	UploaderVoiceType UploaderFileType = "voice"
+	// UploaderVideoNoteType is the multipart field name for video-note uploads.
+	UploaderVideoNoteType UploaderFileType = "video_note"
+	// UploaderThumbnailType is the multipart field name for thumbnail uploads.
+	UploaderThumbnailType UploaderFileType = "thumbnail"
+	// UploaderStickerType is the multipart field name for sticker uploads.
+	UploaderStickerType UploaderFileType = "sticker"
+	// UploaderCertificateType is the multipart field name for webhook certificate uploads.
+	UploaderCertificateType UploaderFileType = "certificate"
+)
+
+// UploaderFileType represents the Telegram form field name for a file upload.
+type UploaderFileType string
+
+// UploaderFile holds the data and metadata for a single file to be uploaded.
+type UploaderFile struct {
+	filename string
+	data     []byte
+	field    UploaderFileType
+}
+
+// NewUploaderFile creates a new UploaderFile, auto-detecting the field type from the file extension.
+// If detection is incorrect, use SetType to override.
+func NewUploaderFile(name string, data []byte) UploaderFile {
+	t := uploaderTypeByExt(name)
+	return UploaderFile{filename: name, data: data, field: t}
+}
+
+// SetType overrides the auto-detected upload field type.
+// For example, use it when a voice file is detected as audio.
+func (f UploaderFile) SetType(t UploaderFileType) UploaderFile {
+	f.field = t
+	return f
+}
+
+// Uploader is a Telegram Bot API client specialized for multipart file uploads.
+//
+// Use Uploader methods when you need to upload binary files directly
+// (InputFile/multipart). For JSON-only calls (file_id, URL, plain params), use API.
+type Uploader struct {
+	api    *API
+	logger *slog.Logger
+}
+
+// NewUploader creates a multipart uploader bound to an API client.
+func NewUploader(api *API) *Uploader {
+	logger := utils.CreateLogger("UPLOADER", utils.GetLoggerLevel())
+	return &Uploader{api, logger}
+}
+
+// Close flushes and closes uploader logger resources.
+// See https://core.telegram.org/bots/api
+func (u *Uploader) Close() error { return u.logger.Close() }
+
+// GetLogger returns uploader logger instance.
+// See https://core.telegram.org/bots/api
+func (u *Uploader) GetLogger() *slog.Logger { return u.logger }
+
+// UploaderRequest is a low-level multipart upload request wrapper.
+//
+// Prefer method-specific helpers such as SendPhoto or SetWebhook. UploaderRequest
+// is intended for advanced use cases where callers manage the method name, files,
+// and request/response types themselves. In that sense it is an unsafe escape
+// hatch compared with the typed uploader API.
+type UploaderRequest[R, P any] struct {
+	method string
+	files  []UploaderFile
+	params P
+	chatId int64
+}
+
+// NewUploaderRequest creates a low-level multipart upload request with no associated chat ID.
+func NewUploaderRequest[R, P any](method string, params P, files ...UploaderFile) UploaderRequest[R, P] {
+	return UploaderRequest[R, P]{method: method, files: files, params: params, chatId: 0}
+}
+
+// NewUploaderRequestWithChatID creates a low-level multipart upload request with an associated chat ID.
+// The chat ID is used for per-chat rate limiting.
+func NewUploaderRequestWithChatID[R, P any](method string, params P, chatId int64, files ...UploaderFile) UploaderRequest[R, P] {
+	return UploaderRequest[R, P]{method: method, files: files, params: params, chatId: chatId}
+}
+
+func (r UploaderRequest[R, P]) doRequest(ctx context.Context, up *Uploader) (R, error) {
+	var zero R
+
+	methodPrefix := ""
+	if up.api.useTestServer {
+		methodPrefix = "/test"
+	}
+	url := fmt.Sprintf("%s/bot%s%s/%s", up.api.apiUrl, up.api.token, methodPrefix, r.method)
+
+	for {
+		if up.api.Limiter != nil {
+			if err := up.api.Limiter.Check(ctx, up.api.dropOverflowLimit, r.chatId); err != nil {
+				return zero, err
+			}
+		}
+
+		buf, contentType, err := prepareMultipart(r.files, r.params)
+		if err != nil {
+			return zero, err
+		}
+		req, err := http.NewRequestWithContext(ctx, "POST", url, buf)
+		if err != nil {
+			return zero, err
+		}
+		req.Header.Set("Content-Type", contentType)
+		req.Header.Set("Accept", "application/json")
+		req.Header.Set("User-Agent", fmt.Sprintf("Laniakea/%s", utils.VersionString))
+		req.ContentLength = int64(buf.Len())
+
+		up.logger.Debugln("UPLOADER REQ", r.method)
+		resp, err := up.api.client.Do(req)
+		if err != nil {
+			return zero, err
+		}
+
+		body, err := readBody(resp.Body)
+		_ = resp.Body.Close()
+		if err != nil {
+			return zero, err
+		}
+		up.logger.Debugln("UPLOADER RES", r.method, string(body))
+
+		response, err := parseBody[R](body)
+		if err != nil {
+			return zero, err
+		}
+
+		if !response.Ok {
+			if response.ErrorCode == 429 && response.Parameters != nil && response.Parameters.RetryAfter != nil {
+				after := *response.Parameters.RetryAfter
+				up.logger.Warnf("Rate limited, retry after %d seconds (chat: %d)", after, r.chatId)
+				if up.api.Limiter != nil {
+					if r.chatId > 0 {
+						up.api.Limiter.SetChatLock(r.chatId, after)
+					} else {
+						up.api.Limiter.SetGlobalLock(after)
+					}
+				}
+
+				select {
+				case <-ctx.Done():
+					return zero, ctx.Err()
+				case <-time.After(time.Duration(after) * time.Second):
+					continue // Повторяем запрос
+				}
+			}
+			return zero, fmt.Errorf("[%d] %s", response.ErrorCode, response.Description)
+		}
+		return response.Result, nil
+	}
+}
+
+// DoWithContext executes the upload request asynchronously via the worker pool.
+// Returns the result or error. Respects context cancellation.
+func (r UploaderRequest[R, P]) DoWithContext(ctx context.Context, up *Uploader) (R, error) {
+	var zero R
+
+	result, err := up.api.pool.submit(ctx, func(ctx context.Context) (any, error) {
+		return r.doRequest(ctx, up)
+	})
+	if err != nil {
+		return zero, err
+	}
+
+	select {
+	case <-ctx.Done():
+		return zero, ctx.Err()
+	case res := <-result:
+		if res.err != nil {
+			return zero, res.err
+		}
+		if val, ok := res.value.(R); ok {
+			return val, nil
+		}
+		return zero, ErrPoolUnexpected
+	}
+}
+
+// Do executes the upload request synchronously with a background context.
+// Use only for simple, non-critical uploads.
+func (r UploaderRequest[R, P]) Do(up *Uploader) (R, error) {
+	return r.DoWithContext(context.Background(), up)
+}
+
+// Internal helper that builds a finalized multipart body from files and params.
+func prepareMultipart[P any](files []UploaderFile, params P) (*bytes.Buffer, string, error) {
+	buf := bytes.NewBuffer(nil)
+	w := multipart.NewWriter(buf)
+
+	for _, file := range files {
+		fw, err := w.CreateFormFile(string(file.field), file.filename)
+		if err != nil {
+			_ = w.Close() // Закрываем, чтобы не было утечки
+			return nil, "", err
+		}
+
+		_, err = fw.Write(file.data)
+		if err != nil {
+			_ = w.Close()
+			return nil, "", err
+		}
+	}
+
+	err := utils.Encode(w, params) // Предполагается, что это записывает в w
+	if err != nil {
+		_ = w.Close()
+		return nil, "", err
+	}
+
+	err = w.Close() // ✅ ОБЯЗАТЕЛЬНО вызвать в конце — иначе запрос битый!
+	if err != nil {
+		return nil, "", err
+	}
+
+	return buf, w.FormDataContentType(), nil
+}
+
+// Internal helper that infers an upload field name from a file extension.
+func uploaderTypeByExt(filename string) UploaderFileType {
+	ext := strings.ToLower(filepath.Ext(filename))
+	switch ext {
+	case ".jpg", ".jpeg", ".png", ".webp", ".bmp":
+		return UploaderPhotoType
+	case ".mp4":
+		return UploaderVideoType
+	case ".mp3", ".m4a":
+		return UploaderAudioType
+	case ".ogg":
+		return UploaderVoiceType
+	default:
+		return UploaderDocumentType
+	}
+}

tgapi/uploader_api_test.go

@@ -0,0 +1,159 @@
+package tgapi
+
+import (
+	"fmt"
+	"io"
+	"mime"
+	"mime/multipart"
+	"net/http"
+	"strings"
+	"testing"
+)
+
+func TestUploaderEncodesJSONFieldsAndLeavesAcceptEncodingToHTTPTransport(t *testing.T) {
+	var (
+		gotPath           string
+		gotAcceptEncoding string
+		gotFields         map[string]string
+		gotFileName       string
+		gotFileData       []byte
+		roundTripErr      error
+	)
+
+	client := &http.Client{
+		Transport: roundTripFunc(func(req *http.Request) (*http.Response, error) {
+			gotPath = req.URL.Path
+			gotAcceptEncoding = req.Header.Get("Accept-Encoding")
+
+			gotFields, gotFileName, gotFileData, roundTripErr = readMultipartRequest(req)
+			if roundTripErr != nil {
+				roundTripErr = fmt.Errorf("readMultipartRequest: %w", roundTripErr)
+			}
+
+			return &http.Response{
+				StatusCode: http.StatusOK,
+				Header:     http.Header{"Content-Type": []string{"application/json"}},
+				Body:       io.NopCloser(strings.NewReader(`{"ok":true,"result":{"message_id":5,"date":1}}`)),
+			}, nil
+		}),
+	}
+
+	api := NewAPI(
+		NewAPIOpts("token").
+			SetAPIUrl("https://example.test").
+			SetHTTPClient(client),
+	)
+	defer func() {
+		if err := api.Close(); err != nil {
+			t.Fatalf("Close returned error: %v", err)
+		}
+	}()
+
+	uploader := NewUploader(api)
+	defer func() {
+		if err := uploader.Close(); err != nil {
+			t.Fatalf("Close returned error: %v", err)
+		}
+	}()
+
+	msg, err := uploader.SendPhoto(
+		UploadPhotoP{
+			ChatID: 42,
+			CaptionEntities: []MessageEntity{{
+				Type:   MessageEntityBold,
+				Offset: 0,
+				Length: 4,
+			}},
+			ReplyMarkup: &ReplyMarkup{
+				InlineKeyboard: [][]InlineKeyboardButton{{
+					{Text: "A", CallbackData: "b"},
+				}},
+			},
+		},
+		NewUploaderFile("photo.jpg", []byte("img")),
+	)
+	if err != nil {
+		t.Fatalf("SendPhoto returned error: %v", err)
+	}
+	if msg.MessageID != 5 {
+		t.Fatalf("unexpected message id: %d", msg.MessageID)
+	}
+	if roundTripErr != nil {
+		t.Fatalf("multipart parse failed: %v", roundTripErr)
+	}
+	if gotPath != "/bottoken/sendPhoto" {
+		t.Fatalf("unexpected request path: %s", gotPath)
+	}
+	if gotAcceptEncoding != "" {
+		t.Fatalf("expected empty Accept-Encoding header, got %q", gotAcceptEncoding)
+	}
+	if got := gotFields["chat_id"]; got != "42" {
+		t.Fatalf("chat_id mismatch: %q", got)
+	}
+	if got := gotFields["caption_entities"]; got != `[{"type":"bold","offset":0,"length":4}]` {
+		t.Fatalf("caption_entities mismatch: %q", got)
+	}
+	if got := gotFields["reply_markup"]; got != `{"inline_keyboard":[[{"text":"A","callback_data":"b"}]]}` {
+		t.Fatalf("reply_markup mismatch: %q", got)
+	}
+	if gotFileName != "photo.jpg" {
+		t.Fatalf("unexpected file name: %q", gotFileName)
+	}
+	if string(gotFileData) != "img" {
+		t.Fatalf("unexpected file content: %q", string(gotFileData))
+	}
+}
+
+func TestNewUploaderFileDetectsFileTypeCaseInsensitively(t *testing.T) {
+	tests := []struct {
+		name     string
+		filename string
+		want     UploaderFileType
+	}{
+		{name: "uppercase photo", filename: "PHOTO.JPG", want: UploaderPhotoType},
+		{name: "uppercase voice", filename: "voice.OGG", want: UploaderVoiceType},
+		{name: "unknown defaults to document", filename: "archive.BIN", want: UploaderDocumentType},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			file := NewUploaderFile(tt.filename, []byte("x"))
+			if file.field != tt.want {
+				t.Fatalf("unexpected uploader field: got %q want %q", file.field, tt.want)
+			}
+		})
+	}
+}
+
+func readMultipartRequest(req *http.Request) (map[string]string, string, []byte, error) {
+	_, params, err := mime.ParseMediaType(req.Header.Get("Content-Type"))
+	if err != nil {
+		return nil, "", nil, err
+	}
+	reader := multipart.NewReader(req.Body, params["boundary"])
+
+	fields := make(map[string]string)
+	var fileName string
+	var fileData []byte
+	for {
+		part, err := reader.NextPart()
+		if err == io.EOF {
+			return fields, fileName, fileData, nil
+		}
+		if err != nil {
+			return nil, "", nil, err
+		}
+
+		data, err := io.ReadAll(part)
+		if err != nil {
+			return nil, "", nil, err
+		}
+
+		if part.FileName() != "" {
+			fileName = part.FileName()
+			fileData = data
+			continue
+		}
+		fields[part.FormName()] = string(data)
+	}
+}

tgapi/uploader_methods.go

@@ -0,0 +1,356 @@
+package tgapi
+
+import "context"
+
+// UploadPhotoP holds parameters for uploading a photo using the Uploader.
+// See https://core.telegram.org/bots/api#sendphoto
+type UploadPhotoP struct {
+	BusinessConnectionID  string `json:"business_connection_id,omitempty"`
+	ChatID                int64  `json:"chat_id"`
+	MessageThreadID       int    `json:"message_thread_id,omitempty"`
+	DirectMessagesTopicID int    `json:"direct_messages_topic_id,omitempty"`
+
+	Caption         string          `json:"caption,omitempty"`
+	ParseMode       ParseMode       `json:"parse_mode,omitempty"`
+	CaptionEntities []MessageEntity `json:"caption_entities,omitempty"`
+
+	ShowCaptionAboveMedia bool   `json:"show_caption_above_media,omitempty"`
+	HasSpoiler            bool   `json:"has_spoiler,omitempty"`
+	DisableNotification   bool   `json:"disable_notification,omitempty"`
+	ProtectContent        bool   `json:"protect_content,omitempty"`
+	AllowPaidBroadcast    bool   `json:"allow_paid_broadcast,omitempty"`
+	MessageEffectID       string `json:"message_effect_id,omitempty"`
+
+	SuggestedPostParameters *SuggestedPostParameters `json:"suggested_post_parameters,omitempty"`
+	ReplyParameters         *ReplyParameters         `json:"reply_parameters,omitempty"`
+	ReplyMarkup             *ReplyMarkup             `json:"reply_markup,omitempty"`
+}
+
+// SendPhoto uploads a photo via multipart and sends it as a message.
+// file is the photo file to upload.
+// See https://core.telegram.org/bots/api#sendphoto
+func (u *Uploader) SendPhoto(params UploadPhotoP, file UploaderFile) (Message, error) {
+	req := NewUploaderRequestWithChatID[Message]("sendPhoto", params, params.ChatID, file)
+	return req.Do(u)
+}
+
+// SendPhotoWithContext is the context-aware variant of SendPhoto.
+// It executes the same request but uses ctx for cancellation and deadlines.
+// SendPhotoWithContext is the context-aware variant of SendPhoto.
+// It executes the same request but uses ctx for cancellation and deadlines.
+// See https://core.telegram.org/bots/api#sendphoto
+func (u *Uploader) SendPhotoWithContext(ctx context.Context, params UploadPhotoP, file UploaderFile) (Message, error) {
+	req := NewUploaderRequestWithChatID[Message]("sendPhoto", params, params.ChatID, file)
+	return req.DoWithContext(ctx, u)
+}
+
+// UploadAudioP holds parameters for uploading an audio file using the Uploader.
+// See https://core.telegram.org/bots/api#sendaudio
+type UploadAudioP struct {
+	BusinessConnectionID  string `json:"business_connection_id,omitempty"`
+	ChatID                int64  `json:"chat_id"`
+	MessageThreadID       int    `json:"message_thread_id,omitempty"`
+	DirectMessagesTopicID int    `json:"direct_messages_topic_id,omitempty"`
+
+	Caption         string          `json:"caption,omitempty"`
+	ParseMode       ParseMode       `json:"parse_mode,omitempty"`
+	CaptionEntities []MessageEntity `json:"caption_entities,omitempty"`
+
+	Duration  int    `json:"duration,omitempty"`
+	Performer string `json:"performer,omitempty"`
+	Title     string `json:"title,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"`
+}
+
+// SendAudio uploads an audio file via multipart and sends it as a message.
+// files are the audio file(s) to upload (typically one file).
+// See https://core.telegram.org/bots/api#sendaudio
+func (u *Uploader) SendAudio(params UploadAudioP, files ...UploaderFile) (Message, error) {
+	req := NewUploaderRequestWithChatID[Message]("sendAudio", params, params.ChatID, files...)
+	return req.Do(u)
+}
+
+// SendAudioWithContext is the context-aware variant of SendAudio.
+// It executes the same request but uses ctx for cancellation and deadlines.
+// SendAudioWithContext is the context-aware variant of SendAudio.
+// It executes the same request but uses ctx for cancellation and deadlines.
+// See https://core.telegram.org/bots/api#sendaudio
+func (u *Uploader) SendAudioWithContext(ctx context.Context, params UploadAudioP, files ...UploaderFile) (Message, error) {
+	req := NewUploaderRequestWithChatID[Message]("sendAudio", params, params.ChatID, files...)
+	return req.DoWithContext(ctx, u)
+}
+
+// UploadDocumentP holds parameters for uploading a document using the Uploader.
+// See https://core.telegram.org/bots/api#senddocument
+type UploadDocumentP struct {
+	BusinessConnectionID  string `json:"business_connection_id,omitempty"`
+	ChatID                int64  `json:"chat_id"`
+	MessageThreadID       int    `json:"message_thread_id,omitempty"`
+	DirectMessagesTopicID int    `json:"direct_messages_topic_id,omitempty"`
+
+	Caption         string          `json:"caption,omitempty"`
+	ParseMode       ParseMode       `json:"parse_mode,omitempty"`
+	CaptionEntities []MessageEntity `json:"caption_entities,omitempty"`
+
+	DisableContentTypeDetection bool   `json:"disable_content_type_detection,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"`
+}
+
+// SendDocument uploads a document via multipart and sends it as a message.
+// files are the document file(s) to upload (typically one file).
+// See https://core.telegram.org/bots/api#senddocument
+func (u *Uploader) SendDocument(params UploadDocumentP, files ...UploaderFile) (Message, error) {
+	req := NewUploaderRequestWithChatID[Message]("sendDocument", params, params.ChatID, files...)
+	return req.Do(u)
+}
+
+// SendDocumentWithContext is the context-aware variant of SendDocument.
+// It executes the same request but uses ctx for cancellation and deadlines.
+// SendDocumentWithContext is the context-aware variant of SendDocument.
+// It executes the same request but uses ctx for cancellation and deadlines.
+// See https://core.telegram.org/bots/api#senddocument
+func (u *Uploader) SendDocumentWithContext(ctx context.Context, params UploadDocumentP, files ...UploaderFile) (Message, error) {
+	req := NewUploaderRequestWithChatID[Message]("sendDocument", params, params.ChatID, files...)
+	return req.DoWithContext(ctx, u)
+}
+
+// UploadVideoP holds parameters for uploading a video using the Uploader.
+// See https://core.telegram.org/bots/api#sendvideo
+type UploadVideoP 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"`
+
+	Duration int `json:"duration,omitempty"`
+	Width    int `json:"width,omitempty"`
+	Height   int `json:"height,omitempty"`
+
+	StartTimestamp  int64           `json:"start_timestamp,omitempty"`
+	Caption         string          `json:"caption,omitempty"`
+	ParseMode       ParseMode       `json:"parse_mode,omitempty"`
+	CaptionEntities []MessageEntity `json:"caption_entities,omitempty"`
+
+	ShowCaptionAboveMedia bool   `json:"show_caption_above_media,omitempty"`
+	HasSpoiler            bool   `json:"has_spoiler,omitempty"`
+	SupportsStreaming     bool   `json:"supports_streaming,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"`
+}
+
+// SendVideo uploads a video via multipart and sends it as a message.
+// files are the video file(s) to upload (typically one file).
+// See https://core.telegram.org/bots/api#sendvideo
+func (u *Uploader) SendVideo(params UploadVideoP, files ...UploaderFile) (Message, error) {
+	req := NewUploaderRequestWithChatID[Message]("sendVideo", params, params.ChatID, files...)
+	return req.Do(u)
+}
+
+// SendVideoWithContext is the context-aware variant of SendVideo.
+// It executes the same request but uses ctx for cancellation and deadlines.
+// SendVideoWithContext is the context-aware variant of SendVideo.
+// It executes the same request but uses ctx for cancellation and deadlines.
+// See https://core.telegram.org/bots/api#sendvideo
+func (u *Uploader) SendVideoWithContext(ctx context.Context, params UploadVideoP, files ...UploaderFile) (Message, error) {
+	req := NewUploaderRequestWithChatID[Message]("sendVideo", params, params.ChatID, files...)
+	return req.DoWithContext(ctx, u)
+}
+
+// UploadAnimationP holds parameters for uploading an animation using the Uploader.
+// See https://core.telegram.org/bots/api#sendanimation
+type UploadAnimationP 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"`
+
+	Duration int `json:"duration,omitempty"`
+	Width    int `json:"width,omitempty"`
+	Height   int `json:"height,omitempty"`
+
+	Caption         string          `json:"caption,omitempty"`
+	ParseMode       ParseMode       `json:"parse_mode,omitempty"`
+	CaptionEntities []MessageEntity `json:"caption_entities,omitempty"`
+
+	ShowCaptionAboveMedia bool   `json:"show_caption_above_media,omitempty"`
+	HasSpoiler            bool   `json:"has_spoiler,omitempty"`
+	DisableNotification   bool   `json:"disable_notification,omitempty"`
+	ProtectContent        bool   `json:"protect_content,omitempty"`
+	AllowPaidBroadcast    bool   `json:"allow_paid_broadcast,omitempty"`
+	MessageEffectID       string `json:"message_effect_id,omitempty"`
+
+	SuggestedPostParameters *SuggestedPostParameters `json:"suggested_post_parameters,omitempty"`
+	ReplyParameters         *ReplyParameters         `json:"reply_parameters,omitempty"`
+	ReplyMarkup             *ReplyMarkup             `json:"reply_markup,omitempty"`
+}
+
+// SendAnimation uploads an animation via multipart and sends it as a message.
+// files are the animation file(s) to upload (typically one file).
+// See https://core.telegram.org/bots/api#sendanimation
+func (u *Uploader) SendAnimation(params UploadAnimationP, files ...UploaderFile) (Message, error) {
+	req := NewUploaderRequestWithChatID[Message]("sendAnimation", params, params.ChatID, files...)
+	return req.Do(u)
+}
+
+// SendAnimationWithContext is the context-aware variant of SendAnimation.
+// It executes the same request but uses ctx for cancellation and deadlines.
+// SendAnimationWithContext is the context-aware variant of SendAnimation.
+// It executes the same request but uses ctx for cancellation and deadlines.
+// See https://core.telegram.org/bots/api#sendanimation
+func (u *Uploader) SendAnimationWithContext(ctx context.Context, params UploadAnimationP, files ...UploaderFile) (Message, error) {
+	req := NewUploaderRequestWithChatID[Message]("sendAnimation", params, params.ChatID, files...)
+	return req.DoWithContext(ctx, u)
+}
+
+// UploadVoiceP holds parameters for uploading a voice note using the Uploader.
+// See https://core.telegram.org/bots/api#sendvoice
+type UploadVoiceP struct {
+	BusinessConnectionID  string `json:"business_connection_id,omitempty"`
+	ChatID                int64  `json:"chat_id"`
+	MessageThreadID       int    `json:"message_thread_id,omitempty"`
+	DirectMessagesTopicID int    `json:"direct_messages_topic_id,omitempty"`
+
+	Caption         string          `json:"caption,omitempty"`
+	ParseMode       ParseMode       `json:"parse_mode,omitempty"`
+	CaptionEntities []MessageEntity `json:"caption_entities,omitempty"`
+	Duration        int             `json:"duration,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"`
+}
+
+// SendVoice uploads a voice note via multipart and sends it as a message.
+// files are the voice file(s) to upload (typically one file).
+// See https://core.telegram.org/bots/api#sendvoice
+func (u *Uploader) SendVoice(params UploadVoiceP, files ...UploaderFile) (Message, error) {
+	req := NewUploaderRequestWithChatID[Message]("sendVoice", params, params.ChatID, files...)
+	return req.Do(u)
+}
+
+// SendVoiceWithContext is the context-aware variant of SendVoice.
+// It executes the same request but uses ctx for cancellation and deadlines.
+// SendVoiceWithContext is the context-aware variant of SendVoice.
+// It executes the same request but uses ctx for cancellation and deadlines.
+// See https://core.telegram.org/bots/api#sendvoice
+func (u *Uploader) SendVoiceWithContext(ctx context.Context, params UploadVoiceP, files ...UploaderFile) (Message, error) {
+	req := NewUploaderRequestWithChatID[Message]("sendVoice", params, params.ChatID, files...)
+	return req.DoWithContext(ctx, u)
+}
+
+// UploadVideoNoteP holds parameters for uploading a video note (rounded video) using the Uploader.
+// See https://core.telegram.org/bots/api#sendvideonote
+type UploadVideoNoteP 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"`
+
+	Duration int `json:"duration,omitempty"`
+	Length   int `json:"length,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"`
+}
+
+// SendVideoNote uploads a video note via multipart and sends it as a message.
+// files are the video note file(s) to upload (typically one file).
+// See https://core.telegram.org/bots/api#sendvideonote
+func (u *Uploader) SendVideoNote(params UploadVideoNoteP, files ...UploaderFile) (Message, error) {
+	req := NewUploaderRequestWithChatID[Message]("sendVideoNote", params, params.ChatID, files...)
+	return req.Do(u)
+}
+
+// SendVideoNoteWithContext is the context-aware variant of SendVideoNote.
+// It executes the same request but uses ctx for cancellation and deadlines.
+// SendVideoNoteWithContext is the context-aware variant of SendVideoNote.
+// It executes the same request but uses ctx for cancellation and deadlines.
+// See https://core.telegram.org/bots/api#sendvideonote
+func (u *Uploader) SendVideoNoteWithContext(ctx context.Context, params UploadVideoNoteP, files ...UploaderFile) (Message, error) {
+	req := NewUploaderRequestWithChatID[Message]("sendVideoNote", params, params.ChatID, files...)
+	return req.DoWithContext(ctx, u)
+}
+
+// UploadChatPhotoP holds parameters for uploading a chat photo using the Uploader.
+// See https://core.telegram.org/bots/api#setchatphoto
+type UploadChatPhotoP struct {
+	ChatID int64 `json:"chat_id"`
+}
+
+// SetChatPhoto uploads a new chat photo.
+// photo is the photo file to upload.
+// See https://core.telegram.org/bots/api#setchatphoto
+func (u *Uploader) SetChatPhoto(params UploadChatPhotoP, photo UploaderFile) (bool, error) {
+	req := NewUploaderRequestWithChatID[bool]("setChatPhoto", params, params.ChatID, photo)
+	return req.Do(u)
+}
+
+// SetChatPhotoWithContext is the context-aware variant of SetChatPhoto.
+// It executes the same request but uses ctx for cancellation and deadlines.
+// SetChatPhotoWithContext is the context-aware variant of SetChatPhoto.
+// It executes the same request but uses ctx for cancellation and deadlines.
+// See https://core.telegram.org/bots/api#setchatphoto
+func (u *Uploader) SetChatPhotoWithContext(ctx context.Context, params UploadChatPhotoP, photo UploaderFile) (bool, error) {
+	req := NewUploaderRequestWithChatID[bool]("setChatPhoto", params, params.ChatID, photo)
+	return req.DoWithContext(ctx, u)
+}
+
+// UploadSetWebhookP holds multipart parameters for the setWebhook method.
+// Use this type when uploading a self-signed certificate file.
+// See https://core.telegram.org/bots/api#setwebhook
+type UploadSetWebhookP struct {
+	URL                string       `json:"url"`
+	IPAddress          string       `json:"ip_address,omitempty"`
+	MaxConnections     int          `json:"max_connections,omitempty"`
+	AllowedUpdates     []UpdateType `json:"allowed_updates,omitempty"`
+	DropPendingUpdates bool         `json:"drop_pending_updates,omitempty"`
+	SecretToken        string       `json:"secret_token,omitempty"`
+}
+
+// SetWebhook uploads a certificate and sets a webhook URL.
+// certificate maps to the multipart field \"certificate\".
+// See https://core.telegram.org/bots/api#setwebhook
+func (u *Uploader) SetWebhook(params UploadSetWebhookP, certificate UploaderFile) (bool, error) {
+	req := NewUploaderRequest[bool]("setWebhook", params, certificate.SetType(UploaderCertificateType))
+	return req.Do(u)
+}
+
+// SetWebhookWithContext is the context-aware variant of SetWebhook.
+// It executes the same request but uses ctx for cancellation and deadlines.
+// See https://core.telegram.org/bots/api#setwebhook
+func (u *Uploader) SetWebhookWithContext(ctx context.Context, params UploadSetWebhookP, certificate UploaderFile) (bool, error) {
+	req := NewUploaderRequest[bool]("setWebhook", params, certificate.SetType(UploaderCertificateType))
+	return req.DoWithContext(ctx, u)
+}

tgapi/users_methods.go

@@ -0,0 +1,102 @@
+package tgapi
+
+import "context"
+
+// GetUserProfilePhotosP holds parameters for the GetUserProfilePhotos method.
+// See https://core.telegram.org/bots/api#getuserprofilephotos
+type GetUserProfilePhotosP struct {
+	UserID int64 `json:"user_id"`
+	Offset int   `json:"offset,omitempty"`
+	Limit  int   `json:"limit,omitempty"`
+}
+
+// GetUserProfilePhotos returns a list of profile pictures for a user.
+// See https://core.telegram.org/bots/api#getuserprofilephotos
+func (api *API) GetUserProfilePhotos(params GetUserProfilePhotosP) (UserProfilePhotos, error) {
+	req := NewRequest[UserProfilePhotos]("getUserProfilePhotos", params)
+	return req.Do(api)
+}
+
+// GetUserProfilePhotosWithContext is the context-aware variant of GetUserProfilePhotos.
+// It executes the same request but uses ctx for cancellation and deadlines.
+// See https://core.telegram.org/bots/api#getuserprofilephotos
+func (api *API) GetUserProfilePhotosWithContext(ctx context.Context, params GetUserProfilePhotosP) (UserProfilePhotos, error) {
+	req := NewRequest[UserProfilePhotos]("getUserProfilePhotos", params)
+	return req.DoWithContext(ctx, api)
+}
+
+// GetUserProfileAudiosP holds parameters for the GetUserProfileAudios method.
+// See https://core.telegram.org/bots/api#getuserprofileaudios
+type GetUserProfileAudiosP struct {
+	UserID int64 `json:"user_id"`
+	Offset int   `json:"offset,omitempty"`
+	Limit  int   `json:"limit,omitempty"`
+}
+
+// GetUserProfileAudios returns a list of profile audios for a user.
+// See https://core.telegram.org/bots/api#getuserprofileaudios
+func (api *API) GetUserProfileAudios(params GetUserProfileAudiosP) (UserProfileAudios, error) {
+	req := NewRequest[UserProfileAudios]("getUserProfileAudios", params)
+	return req.Do(api)
+}
+
+// GetUserProfileAudiosWithContext is the context-aware variant of GetUserProfileAudios.
+// It executes the same request but uses ctx for cancellation and deadlines.
+// See https://core.telegram.org/bots/api#getuserprofileaudios
+func (api *API) GetUserProfileAudiosWithContext(ctx context.Context, params GetUserProfileAudiosP) (UserProfileAudios, error) {
+	req := NewRequest[UserProfileAudios]("getUserProfileAudios", params)
+	return req.DoWithContext(ctx, api)
+}
+
+// SetUserEmojiStatusP holds parameters for the SetUserEmojiStatus method.
+// See https://core.telegram.org/bots/api#setuseremojistatus
+type SetUserEmojiStatusP struct {
+	UserID         int64  `json:"user_id"`
+	EmojiID        string `json:"emoji_status_custom_emoji_id,omitempty"`
+	ExpirationDate int    `json:"emoji_status_expiration_date,omitempty"`
+}
+
+// SetUserEmojiStatus sets a custom emoji status for a user.
+// Returns true on success.
+// See https://core.telegram.org/bots/api#setuseremojistatus
+func (api *API) SetUserEmojiStatus(params SetUserEmojiStatusP) (bool, error) {
+	req := NewRequest[bool]("setUserEmojiStatus", params)
+	return req.Do(api)
+}
+
+// SetUserEmojiStatusWithContext is the context-aware variant of SetUserEmojiStatus.
+// It executes the same request but uses ctx for cancellation and deadlines.
+// See https://core.telegram.org/bots/api#setuseremojistatus
+func (api *API) SetUserEmojiStatusWithContext(ctx context.Context, params SetUserEmojiStatusP) (bool, error) {
+	req := NewRequest[bool]("setUserEmojiStatus", params)
+	return req.DoWithContext(ctx, api)
+}
+
+// GetUserGiftsP holds parameters for the GetUserGifts method.
+// See https://core.telegram.org/bots/api#getusergifts
+type GetUserGiftsP struct {
+	UserID                      int64  `json:"user_id"`
+	ExcludeUnlimited            bool   `json:"exclude_unlimited,omitempty"`
+	ExcludeLimitedUpgradable    bool   `json:"exclude_limited_upgradable,omitempty"`
+	ExcludeLimitedNonUpgradable bool   `json:"exclude_limited_non_upgradable,omitempty"`
+	ExcludeUnique               bool   `json:"exclude_unique,omitempty"`
+	ExcludeFromBlockchain       bool   `json:"exclude_from_blockchain,omitempty"`
+	SortByPrice                 bool   `json:"sort_by_price,omitempty"`
+	Offset                      string `json:"offset,omitempty"`
+	Limit                       int    `json:"limit,omitempty"`
+}
+
+// GetUserGifts returns gifts owned by a user.
+// See https://core.telegram.org/bots/api#getusergifts
+func (api *API) GetUserGifts(params GetUserGiftsP) (OwnedGifts, error) {
+	req := NewRequest[OwnedGifts]("getUserGifts", params)
+	return req.Do(api)
+}
+
+// GetUserGiftsWithContext is the context-aware variant of GetUserGifts.
+// It executes the same request but uses ctx for cancellation and deadlines.
+// See https://core.telegram.org/bots/api#getusergifts
+func (api *API) GetUserGiftsWithContext(ctx context.Context, params GetUserGiftsP) (OwnedGifts, error) {
+	req := NewRequest[OwnedGifts]("getUserGifts", params)
+	return req.DoWithContext(ctx, api)
+}

tgapi/users_types.go

@@ -0,0 +1,52 @@
+package tgapi
+
+// User represents a Telegram user or bot.
+// See https://core.telegram.org/bots/api#user
+type User struct {
+	ID                        int64   `json:"id"`
+	IsBot                     bool    `json:"is_bot"`
+	FirstName                 string  `json:"first_name"`
+	LastName                  *string `json:"last_name,omitempty"`
+	Username                  *string `json:"username,omitempty"`
+	LanguageCode              *string `json:"language_code,omitempty"`
+	IsPremium                 *bool   `json:"is_premium,omitempty"`
+	AddedToAttachmentMenu     *bool   `json:"added_to_attachment_menu,omitempty"`
+	CanJoinGroups             *bool   `json:"can_join_groups,omitempty"`
+	CanReadAllGroupMessages   *bool   `json:"can_read_all_group_messages,omitempty"`
+	SupportsInlineQueries     *bool   `json:"supports_inline_queries,omitempty"`
+	CanConnectToBusiness      *bool   `json:"can_connect_to_business,omitempty"`
+	HasMainWebApp             *bool   `json:"has_main_web_app,omitempty"`
+	HasTopicsEnabled          *bool   `json:"has_topics_enabled,omitempty"`
+	AllowsUsersToCreateTopics *bool   `json:"allows_users_to_create_topics,omitempty"`
+}
+
+// UserProfilePhotos represents a user's profile photos.
+// See https://core.telegram.org/bots/api#userprofilephotos
+type UserProfilePhotos struct {
+	TotalCount int           `json:"total_count"`
+	Photos     [][]PhotoSize `json:"photos"`
+}
+
+// UserProfileAudios represents a user's profile audios.
+// See https://core.telegram.org/bots/api#userprofileaudios
+type UserProfileAudios struct {
+	TotalCount int     `json:"total_count"`
+	Audios     []Audio `json:"audios"`
+}
+
+// UserRating represents a user's rating with level progression.
+// See https://core.telegram.org/bots/api#userrating
+type UserRating struct {
+	Level              int `json:"level"`
+	Rating             int `json:"rating"`
+	CurrentLevelRating int `json:"current_level_rating"`
+	NextLevelRating    int `json:"next_level_rating"`
+}
+
+// Birthdate represents a user's birthdate.
+// See https://core.telegram.org/bots/api#birthdate
+type Birthdate struct {
+	Day   int `json:"day"`
+	Month int `json:"month"`
+	Year  int `json:"year"`
+}

types.go

@@ -1,226 +0,0 @@
-package laniakea
-
-import "git.nix13.pw/scuroneko/extypes"
-
-type Update struct {
-	UpdateID               int                          `json:"update_id"`
-	Message                *Message                     `json:"message"`
-	EditedMessage          *Message                     `json:"edited_message,omitempty"`
-	ChannelPost            *Message                     `json:"channel_post,omitempty"`
-	EditedChannelPost      *Message                     `json:"edited_channel_post,omitempty"`
-	BusinessConnection     *BusinessConnection          `json:"business_connection,omitempty"`
-	BusinessMessage        *Message                     `json:"business_message,omitempty"`
-	EditedBusinessMessage  *Message                     `json:"edited_business_message,omitempty"`
-	DeletedBusinessMessage *Message                     `json:"deleted_business_messages,omitempty"`
-	MessageReaction        *MessageReactionUpdated      `json:"message_reaction,omitempty"`
-	MessageReactionCount   *MessageReactionCountUpdated `json:"message_reaction_count,omitempty"`
-	CallbackQuery          *CallbackQuery               `json:"callback_query,omitempty"`
-	InlineQuery            int
-	ChosenInlineResult     int
-}
-
-type User struct {
-	ID                      int    `json:"id"`
-	IsBot                   bool   `json:"is_bot"`
-	FirstName               string `json:"first_name"`
-	LastName                string `json:"last_name,omitempty"`
-	Username                string `json:"username,omitempty"`
-	LanguageCode            string `json:"language_code,omitempty"`
-	IsPremium               bool   `json:"is_premium,omitempty"`
-	AddedToAttachmentMenu   bool   `json:"added_to_attachment_menu,omitempty"`
-	CanJoinGroups           bool   `json:"can_join_groups,omitempty"`
-	CanReadAllGroupMessages bool   `json:"can_read_all_group_messages,omitempty"`
-	SupportsInlineQueries   bool   `json:"supports_inline_queries,omitempty"`
-	CanConnectToBusiness    bool   `json:"can_connect_to_business,omitempty"`
-	HasMainWebApp           bool   `json:"has_main_web_app,omitempty"`
-}
-
-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"`
-}
-
-type MessageReplyMarkup struct {
-	InlineKeyboard [][]InlineKeyboardButton `json:"inline_keyboard"`
-}
-
-type Message struct {
-	MessageID       int    `json:"message_id"`
-	MessageThreadID int    `json:"message_thread_id,omitempty"`
-	From            *User  `json:"from,omitempty"`
-	Chat            *Chat  `json:"chat,omitempty"`
-	Text            string `json:"text"`
-
-	Photo          extypes.Slice[*PhotoSize] `json:"photo,omitempty"`
-	Caption        string                    `json:"caption,omitempty"`
-	ReplyToMessage *Message                  `json:"reply_to_message"`
-
-	ReplyMarkup *MessageReplyMarkup `json:"reply_markup,omitempty"`
-}
-
-type InaccessableMessage struct {
-	Chat      *Chat `json:"chat"`
-	MessageID int   `json:"message_id"`
-	Date      int   `json:"date"`
-}
-
-type MaybeInaccessibleMessage struct {
-}
-
-type MessageEntity struct {
-	Type          string `json:"type"`
-	Offset        int    `json:"offset"`
-	Length        int    `json:"length"`
-	URL           string `json:"url,omitempty"`
-	User          *User  `json:"user,omitempty"`
-	Language      string `json:"language,omitempty"`
-	CustomEmojiID string `json:"custom_emoji_id,omitempty"`
-}
-
-type ReplyParameters struct {
-	MessageID int `json:"message_id"`
-	ChatID    int `json:"chat_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"`
-}
-
-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"`
-}
-
-type LinkPreviewOptions struct {
-	IsDisabled       bool   `json:"is_disabled,omitempty"`
-	URL              string `json:"url,omitempty"`
-	PreferSmallMedia bool   `json:"prefer_small_media,omitempty"`
-	PreferLargeMedia bool   `json:"prefer_large_media,omitempty"`
-	ShowAboveText    bool   `json:"show_above_text,omitempty"`
-}
-
-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"`
-
-	RemoveKeyboard bool `json:"remove_keyboard,omitempty"`
-
-	ForceReply bool `json:"force_reply,omitempty"`
-}
-type InlineKeyboardMarkup struct {
-	InlineKeyboard [][]InlineKeyboardButton `json:"inline_keyboard,omitempty"`
-}
-
-type InlineKeyboardButton struct {
-	Text         string `json:"text"`
-	URL          string `json:"url,omitempty"`
-	CallbackData string `json:"callback_data,omitempty"`
-}
-
-type ReplyKeyboardMarkup struct {
-	Keyboard [][]int `json:"keyboard"`
-}
-
-type CallbackQuery struct {
-	ID      string   `json:"id"`
-	From    *User    `json:"from"`
-	Message *Message `json:"message"`
-
-	Data string `json:"data"`
-}
-
-type BusinessConnection struct {
-	ID         string `json:"id"`
-	User       *User  `json:"user"`
-	UserChatID int    `json:"user_chat_id"`
-	Date       int    `json:"date"`
-	CanReply   bool   `json:"can_reply"`
-	IsEnabled  bool   `json:"id_enabled"`
-}
-
-type MessageReactionUpdated struct {
-	Chat        *Chat           `json:"chat"`
-	MessageID   int             `json:"message_id"`
-	User        *User           `json:"user,omitempty"`
-	ActorChat   *Chat           `json:"actor_chat"`
-	Date        int             `json:"date"`
-	OldReaction []*ReactionType `json:"old_reaction"`
-	NewReaction []*ReactionType `json:"new_reaction"`
-}
-
-type MessageReactionCountUpdated struct {
-	Chat      *Chat            `json:"chat"`
-	MessageID int              `json:"message_id"`
-	Date      int              `json:"date"`
-	Reactions []*ReactionCount `json:"reactions"`
-}
-
-type ReactionType struct {
-	Type string `json:"type"`
-}
-type ReactionTypeEmoji struct {
-	ReactionType
-	Emoji string `json:"emoji"`
-}
-type ReactionTypeCustomEmoji struct {
-	ReactionType
-	CustomEmojiID string `json:"custom_emoji_id"`
-}
-type ReactionTypePaid struct {
-	ReactionType
-}
-type ReactionCount struct {
-	Type       *ReactionType `json:"type"`
-	TotalCount int           `json:"total_count"`
-}
-
-type File struct {
-	FileId       string `json:"file_id"`
-	FileUniqueID string `json:"file_unique_id"`
-	FileSize     int    `json:"file_size,omitempty"`
-	FilePath     string `json:"file_path,omitempty"`
-}
-
-type ChatActions string
-
-const (
-	ChatActionTyping          ChatActions = "typing"
-	ChatActionUploadPhoto     ChatActions = "upload_photo"
-	ChatActionUploadVideo     ChatActions = "upload_video"
-	ChatActionUploadVoice     ChatActions = "upload_voice"
-	ChatActionUploadDocument  ChatActions = "upload_document"
-	ChatActionChooseSticker   ChatActions = "choose_sticker"
-	ChatActionFindLocation    ChatActions = "find_location"
-	ChatActionUploadVideoNone ChatActions = "upload_video_none"
-)
-
-type SuggestedPostPrice struct {
-	Currency string `json:"currency"`
-	Amount   int    `json:"amount"`
-}
-type SuggestedPostInfo struct {
-	State    string             `json:"state"` //State of the suggested post. Currently, it can be one of “pending”, “approved”, “declined”.
-	Price    SuggestedPostPrice `json:"price"`
-	SendDate int                `json:"send_date"`
-}
-type SuggestedPostParameters struct {
-	Price    SuggestedPostPrice `json:"price"`
-	SendDate int                `json:"send_date"`
-}

uploader.go

@@ -1,144 +0,0 @@
-package laniakea
-
-import (
-	"bytes"
-	"encoding/json"
-	"fmt"
-	"io"
-	"mime/multipart"
-	"net/http"
-	"path/filepath"
-
-	"git.nix13.pw/scuroneko/slog"
-)
-
-type Uploader struct {
-	api    *Api
-	logger *slog.Logger
-}
-
-func NewUploader(api *Api) *Uploader {
-	logger := slog.CreateLogger().Level(GetLoggerLevel()).Prefix("UPLOADER")
-	logger.AddWriter(logger.CreateJsonStdoutWriter())
-	return &Uploader{api, logger}
-}
-func (u *Uploader) Close() {
-	u.logger.Close()
-}
-
-type UploaderFileType string
-
-const (
-	UploaderPhotoType     UploaderFileType = "photo"
-	UploaderVideoType     UploaderFileType = "video"
-	UploaderAudioType     UploaderFileType = "audio"
-	UploaderDocumentType  UploaderFileType = "document"
-	UploaderVoiceType     UploaderFileType = "voice"
-	UploaderVideoNoteType UploaderFileType = "video_note"
-)
-
-type UploaderFile struct {
-	filename string
-	data     []byte
-	t        UploaderFileType
-}
-
-func NewUploaderFile(name string, data []byte) UploaderFile {
-	t := uploaderTypeByExt(name)
-	return UploaderFile{filename: name, data: data, t: t}
-}
-
-// SetType used when auto-detect failed. I.e. you sending a voice message, but it detects as audio
-func (f UploaderFile) SetType(t UploaderFileType) UploaderFile {
-	f.t = t
-	return f
-}
-
-type UploaderRequest[R, P any] struct {
-	method string
-	file   UploaderFile
-	params P
-}
-
-func NewUploaderRequest[R, P any](method string, file UploaderFile, params P) UploaderRequest[R, P] {
-	return UploaderRequest[R, P]{method, file, params}
-}
-
-func (u UploaderRequest[R, P]) Do(up *Uploader) (*R, error) {
-	url := fmt.Sprintf("https://api.telegram.org/bot%s/%s", up.api.token, u.method)
-
-	buf := bytes.NewBuffer(nil)
-	w := multipart.NewWriter(buf)
-
-	fw, err := w.CreateFormFile(string(u.file.t), u.file.filename)
-	if err != nil {
-		w.Close()
-		return nil, err
-	}
-	_, err = fw.Write(u.file.data)
-	if err != nil {
-		w.Close()
-		return nil, err
-	}
-	err = Encode(w, u.params)
-	if err != nil {
-		w.Close()
-		return nil, err
-	}
-	err = w.Close()
-	if err != nil {
-		return nil, err
-	}
-
-	req, err := http.NewRequest("POST", url, buf)
-	if err != nil {
-		return nil, err
-	}
-	req.Header.Set("Content-Type", w.FormDataContentType())
-	up.logger.Debugln("UPLOADER REQ", u.method)
-	res, err := http.DefaultClient.Do(req)
-	if err != nil {
-		return nil, err
-	}
-	defer res.Body.Close()
-
-	body, err := io.ReadAll(res.Body)
-	if err != nil {
-		return nil, err
-	}
-	up.logger.Debugln("UPLOADER RES", u.method, string(body))
-	if res.StatusCode != http.StatusOK {
-		return nil, fmt.Errorf("[%d] %s", res.StatusCode, string(body))
-	}
-
-	response := new(ApiResponse[*R])
-	err = json.Unmarshal(body, response)
-	if err != nil {
-		return nil, err
-	}
-	if !response.Ok {
-		return nil, fmt.Errorf("[%d] %s", response.ErrorCode, response.Description)
-	}
-	return response.Result, nil
-}
-
-func (u *Uploader) UploadPhoto(file UploaderFile, params SendPhotoBaseP) (*Message, error) {
-	req := NewUploaderRequest[Message]("sendPhoto", file, params)
-	return req.Do(u)
-}
-
-func uploaderTypeByExt(filename string) UploaderFileType {
-	ext := filepath.Ext(filename)
-	switch ext {
-	case ".jpg", ".jpeg", ".png", ".webp", ".bmp":
-		return UploaderPhotoType
-	case ".mp4":
-		return UploaderVideoType
-	case ".mp3", ".m4a":
-		return UploaderAudioType
-	case ".ogg":
-		return UploaderVoiceType
-	default:
-		return UploaderDocumentType
-	}
-}

utils.go

@@ -1,75 +1,24 @@
 package laniakea
 
 import (
-	"encoding/json"
-	"fmt"
-	"os"
 	"strings"
 
-	"git.nix13.pw/scuroneko/slog"
+	"git.scuroneko.dev/scuroneko/laniakea/utils"
 )
 
-func GetLoggerLevel() slog.LogLevel {
-	level := slog.FATAL
-	if os.Getenv("DEBUG") == "true" {
-		level = slog.DEBUG
+// Ptr returns a pointer to v.
+func Ptr[T any](v T) *T { return &v }
+
+// Val returns dereferenced pointer value or def when p is nil.
+func Val[T any](p *T, def T) T {
+	if p != nil {
+		return *p
 	}
-	return level
-}
-
-// MapToStruct unsafe function
-func MapToStruct(m map[string]any, s any) error {
-	data, err := json.Marshal(m)
-	if err != nil {
-		return err
-	}
-	err = json.Unmarshal(data, s)
-	return err
-}
-
-// SliceToStruct unsafe function
-func SliceToStruct(sl []any, s any) error {
-	data, err := json.Marshal(sl)
-	if err != nil {
-		return err
-	}
-	err = json.Unmarshal(data, s)
-	return err
-}
-
-// AnyToStruct unsafe function
-func AnyToStruct(src, dest any) error {
-	data, err := json.Marshal(src)
-	if err != nil {
-		return err
-	}
-	err = json.Unmarshal(data, dest)
-	return err
-}
-
-func MapToJson(m map[string]any) (string, error) {
-	data, err := json.Marshal(m)
-	return string(data), err
-}
-
-func StructToMap(s any) (map[string]any, error) {
-	data, err := json.Marshal(s)
-	if err != nil {
-		return nil, err
-	}
-	m := make(map[string]any)
-	err = json.Unmarshal(data, &m)
-	return m, err
-}
-
-func Map[T, V any](ts []T, fn func(T) V) []V {
-	result := make([]V, len(ts))
-	for i, t := range ts {
-		result[i] = fn(t)
-	}
-	return result
+	return def
 }
 
+// EscapeMarkdown escapes special characters for legacy Telegram Markdown.
+// Deprecated: Use EscapeMarkdownV2.
 func EscapeMarkdown(s string) string {
 	s = strings.ReplaceAll(s, "_", `\_`)
 	s = strings.ReplaceAll(s, "*", `\*`)
@@ -77,10 +26,42 @@ func EscapeMarkdown(s string) string {
 	return strings.ReplaceAll(s, "`", "\\`")
 }
 
+// EscapeHTML escapes special characters for Telegram HTML parse mode.
+func EscapeHTML(s string) string {
+	s = strings.ReplaceAll(s, "&", "&")
+	s = strings.ReplaceAll(s, "<", "&lt;")
+	s = strings.ReplaceAll(s, ">", "&gt;")
+	return s
+}
+
+// EscapeMarkdownV2 escapes special characters for Telegram MarkdownV2.
+// https://core.telegram.org/bots/api#markdownv2-style
 func EscapeMarkdownV2(s string) string {
-	symbols := []string{"_", "*", "[", "]", "(", ")", "~", "`", ">", "#", "+", "-", "=", "|", "{", "}", ".", "!"}
+	symbols := []string{"\\", "_", "*", "[", "]", "(", ")", "~", "`", ">", "#", "+", "-", "=", "|", "{", "}", ".", "!"}
 	for _, symbol := range symbols {
-		s = strings.ReplaceAll(s, symbol, fmt.Sprintf("\\%s", symbol))
+		s = strings.ReplaceAll(s, symbol, "\\"+symbol)
 	}
 	return s
 }
+
+// EscapePunctuation escapes '.', '!' and '-' for MarkdownV2 fragments.
+func EscapePunctuation(s string) string {
+	symbols := []string{".", "!", "-"}
+	for _, symbol := range symbols {
+		s = strings.ReplaceAll(s, symbol, "\\"+symbol)
+	}
+	return s
+}
+
+const (
+	// VersionString re-exports the module version string.
+	VersionString = utils.VersionString
+	// VersionMajor re-exports the module major version.
+	VersionMajor = utils.VersionMajor
+	// VersionMinor re-exports the module minor version.
+	VersionMinor = utils.VersionMinor
+	// VersionPatch re-exports the module patch version.
+	VersionPatch = utils.VersionPatch
+	// VersionBeta re-exports the module prerelease counter.
+	VersionBeta = utils.VersionBeta
+)

utils/limiter.go

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

utils/limiter_test.go

@@ -0,0 +1,41 @@
+package utils
+
+import (
+	"context"
+	"errors"
+	"testing"
+	"time"
+)
+
+func TestRateLimiterCheckDropOverflowHonorsGlobalLock(t *testing.T) {
+	rl := NewRateLimiter()
+	rl.SetGlobalLock(1)
+
+	if err := rl.Check(context.Background(), true, 0); !errors.Is(err, ErrDropOverflow) {
+		t.Fatalf("expected ErrDropOverflow, got %v", err)
+	}
+}
+
+func TestRateLimiterChatLocksAreScopedPerChat(t *testing.T) {
+	rl := NewRateLimiter()
+	rl.SetChatLock(42, 1)
+
+	if rl.Allow(42) {
+		t.Fatal("expected locked chat to be rejected")
+	}
+	if !rl.Allow(7) {
+		t.Fatal("expected unrelated chat to remain allowed")
+	}
+}
+
+func TestRateLimiterGlobalWaitRespectsContextCancellation(t *testing.T) {
+	rl := NewRateLimiter()
+	rl.SetGlobalLock(1)
+
+	ctx, cancel := context.WithTimeout(context.Background(), 10*time.Millisecond)
+	defer cancel()
+
+	if err := rl.GlobalWait(ctx); !errors.Is(err, context.DeadlineExceeded) {
+		t.Fatalf("expected DeadlineExceeded, got %v", err)
+	}
+}

utils/multipart.go

@@ -0,0 +1,114 @@
+package utils
+
+import (
+	"encoding/json"
+	"fmt"
+	"mime/multipart"
+	"reflect"
+	"slices"
+	"strconv"
+	"strings"
+)
+
+// Encode writes struct fields into multipart form-data using json tags as field names.
+func Encode[T any](w *multipart.Writer, req T) error {
+	v := unwrapMultipartValue(reflect.ValueOf(req))
+	if !v.IsValid() || v.Kind() != reflect.Struct {
+		return fmt.Errorf("req must be a struct")
+	}
+
+	t := v.Type()
+	for i := 0; i < v.NumField(); i++ {
+		field := v.Field(i)
+		fieldType := t.Field(i)
+
+		jsonTag := fieldType.Tag.Get("json")
+		if jsonTag == "" {
+			jsonTag = fieldType.Name
+		}
+
+		parts := strings.Split(jsonTag, ",")
+		fieldName := parts[0]
+		if fieldName == "" {
+			fieldName = fieldType.Name
+		}
+		if fieldName == "-" {
+			continue
+		}
+
+		// Handle omitempty
+		isEmpty := field.IsZero()
+		if slices.Contains(parts, "omitempty") && isEmpty {
+			continue
+		}
+
+		if err := writeMultipartField(w, fieldName, fieldType.Tag.Get("filename"), field); err != nil {
+			return err
+		}
+	}
+
+	return nil
+}
+
+func unwrapMultipartValue(v reflect.Value) reflect.Value {
+	for v.IsValid() && (v.Kind() == reflect.Pointer || v.Kind() == reflect.Interface) {
+		if v.IsNil() {
+			return reflect.Value{}
+		}
+		v = v.Elem()
+	}
+	return v
+}
+
+func writeMultipartField(w *multipart.Writer, fieldName, filename string, field reflect.Value) error {
+	value := unwrapMultipartValue(field)
+	if !value.IsValid() {
+		return nil
+	}
+
+	switch value.Kind() {
+	case reflect.String:
+		return writeMultipartValue(w, fieldName, []byte(value.String()))
+	case reflect.Int, reflect.Int8, reflect.Int16, reflect.Int32, reflect.Int64:
+		return writeMultipartValue(w, fieldName, []byte(strconv.FormatInt(value.Int(), 10)))
+	case reflect.Uint, reflect.Uint8, reflect.Uint16, reflect.Uint32, reflect.Uint64:
+		return writeMultipartValue(w, fieldName, []byte(strconv.FormatUint(value.Uint(), 10)))
+	case reflect.Float32:
+		return writeMultipartValue(w, fieldName, []byte(strconv.FormatFloat(value.Float(), 'f', -1, 32)))
+	case reflect.Float64:
+		return writeMultipartValue(w, fieldName, []byte(strconv.FormatFloat(value.Float(), 'f', -1, 64)))
+	case reflect.Bool:
+		return writeMultipartValue(w, fieldName, []byte(strconv.FormatBool(value.Bool())))
+	case reflect.Slice:
+		if value.Type().Elem().Kind() == reflect.Uint8 {
+			if filename == "" {
+				filename = fieldName
+			}
+			fw, err := w.CreateFormFile(fieldName, filename)
+			if err != nil {
+				return err
+			}
+			_, err = fw.Write(value.Bytes())
+			return err
+		}
+	}
+
+	// Telegram expects nested objects and arrays in multipart requests as JSON strings.
+	data, err := json.Marshal(value.Interface())
+	if err != nil {
+		return err
+	}
+	if string(data) == "null" {
+		return nil
+	}
+	return writeMultipartValue(w, fieldName, data)
+}
+
+func writeMultipartValue(w *multipart.Writer, fieldName string, value []byte) error {
+	fw, err := w.CreateFormField(fieldName)
+	if err != nil {
+		return err
+	}
+	_, err = fw.Write(value)
+	return err
+}

utils/multipart_test.go

@@ -0,0 +1,85 @@
+package utils_test
+
+import (
+	"bytes"
+	"io"
+	"mime/multipart"
+	"testing"
+
+	"git.scuroneko.dev/scuroneko/laniakea/tgapi"
+	"git.scuroneko.dev/scuroneko/laniakea/utils"
+)
+
+type multipartEncodeParams struct {
+	ChatID          int64                  `json:"chat_id"`
+	MessageThreadID *int                   `json:"message_thread_id,omitempty"`
+	ReplyMarkup     *tgapi.ReplyMarkup     `json:"reply_markup,omitempty"`
+	CaptionEntities []tgapi.MessageEntity  `json:"caption_entities,omitempty"`
+	ReplyParameters *tgapi.ReplyParameters `json:"reply_parameters,omitempty"`
+}
+
+func TestEncodeMultipartJSONFields(t *testing.T) {
+	threadID := 7
+	params := multipartEncodeParams{
+		ChatID:          42,
+		MessageThreadID: &threadID,
+		ReplyMarkup: &tgapi.ReplyMarkup{
+			InlineKeyboard: [][]tgapi.InlineKeyboardButton{{
+				{Text: "A", CallbackData: "b"},
+			}},
+		},
+		CaptionEntities: []tgapi.MessageEntity{{
+			Type:   tgapi.MessageEntityBold,
+			Offset: 0,
+			Length: 4,
+		}},
+	}
+
+	body := bytes.NewBuffer(nil)
+	writer := multipart.NewWriter(body)
+	if err := utils.Encode(writer, params); err != nil {
+		t.Fatalf("Encode returned error: %v", err)
+	}
+	if err := writer.Close(); err != nil {
+		t.Fatalf("writer.Close returned error: %v", err)
+	}
+
+	got := readMultipartFields(t, body.Bytes(), writer.Boundary())
+	if got["chat_id"] != "42" {
+		t.Fatalf("chat_id mismatch: %q", got["chat_id"])
+	}
+	if got["message_thread_id"] != "7" {
+		t.Fatalf("message_thread_id mismatch: %q", got["message_thread_id"])
+	}
+	if got["reply_markup"] != `{"inline_keyboard":[[{"text":"A","callback_data":"b"}]]}` {
+		t.Fatalf("reply_markup mismatch: %q", got["reply_markup"])
+	}
+	if got["caption_entities"] != `[{"type":"bold","offset":0,"length":4}]` {
+		t.Fatalf("caption_entities mismatch: %q", got["caption_entities"])
+	}
+	if _, ok := got["reply_parameters"]; ok {
+		t.Fatalf("reply_parameters should be omitted when nil")
+	}
+}
+
+func readMultipartFields(t *testing.T, body []byte, boundary string) map[string]string {
+	t.Helper()
+
+	reader := multipart.NewReader(bytes.NewReader(body), boundary)
+	fields := make(map[string]string)
+	for {
+		part, err := reader.NextPart()
+		if err == io.EOF {
+			return fields
+		}
+		if err != nil {
+			t.Fatalf("NextPart returned error: %v", err)
+		}
+
+		data, err := io.ReadAll(part)
+		if err != nil {
+			t.Fatalf("ReadAll returned error: %v", err)
+		}
+		fields[part.FormName()] = string(data)
+	}
+}

utils/utils.go

@@ -0,0 +1,42 @@
+package utils
+
+import (
+	"os"
+
+	"git.scuroneko.dev/scuroneko/slog"
+)
+
+// GetLoggerLevel returns DEBUG when DEBUG=true in env, otherwise FATAL.
+func GetLoggerLevel() slog.LogLevel {
+	level := slog.FATAL
+	if os.Getenv("DEBUG") == "true" {
+		level = slog.DEBUG
+	}
+	return level
+}
+
+// CreateLogger creates a logger with the shared default policy:
+// JSON stdout output, provided prefix, and provided level.
+func CreateLogger(prefix string, level slog.LogLevel) *slog.Logger {
+	logger := slog.CreateLogger().Level(level)
+	if prefix != "" {
+		logger.Prefix(prefix)
+	}
+	logger.AddWriter(logger.CreateJsonStdoutWriter())
+	return logger
+}
+
+// CreateFileLogger creates a logger with the shared default policy and appends
+// file output to the provided path.
+//
+// The returned logger is always non-nil. When file writer creation fails, the
+// logger still writes to stdout and the error is returned to the caller.
+func CreateFileLogger(prefix string, level slog.LogLevel, filePath string) (*slog.Logger, error) {
+	logger := CreateLogger(prefix, level)
+	fileWriter, err := logger.CreateTextFileWriter(filePath)
+	if err != nil {
+		return logger, err
+	}
+	logger.AddWriter(fileWriter)
+	return logger, nil
+}

utils/utils_test.go

@@ -0,0 +1,34 @@
+package utils
+
+import (
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"git.scuroneko.dev/scuroneko/slog"
+)
+
+func TestCreateFileLoggerWritesToConfiguredFile(t *testing.T) {
+	logPath := filepath.Join(t.TempDir(), "main.log")
+
+	logger, err := CreateFileLogger("TEST", slog.DEBUG, logPath)
+	if err != nil {
+		t.Fatalf("CreateFileLogger returned error: %v", err)
+	}
+	logger.Infoln("hello from file logger")
+	if err := logger.Close(); err != nil {
+		t.Fatalf("Close returned error: %v", err)
+	}
+
+	data, err := os.ReadFile(logPath)
+	if err != nil {
+		t.Fatalf("ReadFile returned error: %v", err)
+	}
+	if !strings.Contains(string(data), "hello from file logger") {
+		t.Fatalf("expected log message in file, got %q", string(data))
+	}
+	if !strings.Contains(string(data), "[TEST]") {
+		t.Fatalf("expected prefix in file, got %q", string(data))
+	}
+}

utils/version.go

@@ -0,0 +1,14 @@
+package utils
+
+const (
+	// VersionString is the module version string.
+	VersionString = "1.0.0-rc.12"
+	// VersionMajor is the module major version.
+	VersionMajor = 1
+	// VersionMinor is the module minor version.
+	VersionMinor = 0
+	// VersionPatch is the module patch version.
+	VersionPatch = 0
+	// VersionBeta is the prerelease counter for the current version.
+	VersionBeta = 12
+)

version.go

@@ -1,8 +0,0 @@
-package laniakea
-
-const (
-	VersionString = "0.4.0"
-	VersionMajor  = 0
-	VersionMinor  = 4
-	VersionPatch  = 0
-)