(new): v1.2 release

README.md

@@ -217,6 +217,12 @@ This split keeps method intent explicit: JSON-only calls go through `API`, file
 
 For advanced cases, `tgapi.NewRequest(...)` and `tgapi.NewUploaderRequest(...)` remain public as low-level escape hatches. They are intentionally less safe than method-specific helpers: callers must supply the correct Telegram method name and compatible request/response types themselves.
 
+Automatic retries after Telegram `429` responses are bounded to three by
+default; configure the cap with `NewAPIOpts(...).SetMaxRetries(...)`. Multipart
+uploads stream the encoded request instead of duplicating the complete body in
+memory. For downloads with an unknown size, use `OpenFileByLinkWithContext` or
+set an explicit bound with `GetFileByLinkLimitWithContext`.
+
 ### App Data
 
 The `T` in `NewBot[T]` is a powerful feature. You can pass any type, but shared dependencies such as database pools, service containers, or API clients should usually use a pointer type.
@@ -273,7 +279,10 @@ plugin.Scene("signup").
 Runners are background tasks that execute alongside the bot runtime. They are registered before the bot starts and launched automatically when the bot starts.
 
 ```go
-import "time"
+import (
+    "context"
+    "time"
+)
 
 // One-shot runner — fires once in a goroutine when the bot starts (default).
 bot.AddRunner(
@@ -284,8 +293,8 @@ bot.AddRunner(
 
 // Periodic runner — fires every 10 minutes in a goroutine.
 bot.AddRunner(
-    laniakea.NewRunner("refresh-stats", func(b *laniakea.Bot[*MyDB]) error {
-        return b.GetAppData().RefreshStats()
+    laniakea.NewContextRunner("refresh-stats", func(ctx context.Context, b *laniakea.Bot[*MyDB]) error {
+        return b.GetAppData().RefreshStats(ctx)
     }).Every(10 * time.Minute),
 )
 
@@ -301,6 +310,9 @@ Builder methods:
 - `Async(bool) *Runner[T]` — if `true` (default), runs in a goroutine; if `false`, blocks runtime startup.
 - `Every(time.Duration) *Runner[T]` — sets the repeat interval. Zero (default) means run once; positive value repeats. Periodic runners require `Async(true)`.
 
+Prefer `NewContextRunner` for I/O and blocking work. Its context is canceled
+when polling or webhook execution stops, allowing shutdown to complete.
+
 ## 🧩 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.
 
@@ -350,7 +362,9 @@ func adminOnlyMiddleware(ctx *laniakea.MessageContext, db *MyDB) bool {
 
 ## ⚙️ 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.
+- **Keyboard Validation**: Call `InlineKeyboard.GetValidated()` before sending untrusted or dynamically generated callback payloads; Telegram limits `callback_data` to 1–64 bytes.
 - **Rate Limiting**: Pass a configured utils.RateLimiter via BotOpts to handle Telegram's rate limits gracefully.
+- **Observers**: Runtime observer callbacks are dispatched asynchronously in order through a bounded queue. Slow observers do not block handlers; overload drops events with sampled warnings, and shutdown drains queued events.
 - **Localization**: `L10n` is safe for concurrent use once attached to the bot.
 - **Custom Update Handlers**: Use `plugin.AddUpdateHandler(...)` for Telegram update types that are not part of the command/payload flow.
 - **Lifecycle**: `RunWithContext(...)` and `RunWebhookWithContext(...)` do not call `Close()` for you. Shut the bot down explicitly, and create a fresh `Bot` for the next run.