Changed

• Updated the generated Telegram schema and client surface to Telegram Bot API 10.3.
• Added the Bot API 10.3 types, methods, unions, and update families to the generated packages.
• Updated ephemeral message sending to use the typed ephemeral_message_parameters contract.
• Added classification for stopped_message_generation updates while preserving chat identity.

This release is aligned with Telegram Bot API 10.3. Update all TeleFlow packages used by an application to 1.0.0-alpha.15 together.

Fixed

• Fixed TelegramApiResponse<TResult> JSON metadata for value-type results such as bool.
• Raw response envelopes now serialize and deserialize valid false results without System.Text.Json rejecting the generated contract.

This hotfix remains aligned with Telegram Bot API 10.2. Update all TeleFlow packages used by an application to 1.0.0-alpha.14.1 together.

Highlights

• Fixed Telegram Bot API 10.2 rich-message ordered-list deserialization for all documented label types: a, A, i, I, and 1.
• Long polling now decodes getUpdates results one update at a time, so one incompatible update no longer discards valid neighboring updates.
• Deterministic schema decode failures are no longer retried as transient Telegram request failures.
• Added ITelegramUpdateDecodeFailurePolicy with explicit fail-closed Stop and application-owned Skip decisions shared by long polling and webhooks.
• Webhooks now distinguish malformed requests from syntactically valid Telegram updates that do not match the installed schema.
• Decode diagnostics include update id, JSON path, and SHA-256 fingerprint without logging the raw payload.

Upgrade

Update every TeleFlow package used by the application to 1.0.0-alpha.14 together.

dotnet add package IWF.TeleFlow.Framework.LongPolling --version 1.0.0-alpha.14
dotnet add package IWF.TeleFlow.Generators --version 1.0.0-alpha.14

The default decode-failure behavior is Stop. Applications opting into Skip must durably quarantine the raw update before returning that decision; otherwise they are explicitly accepting unrecoverable update loss.

This release remains aligned with Telegram Bot API 10.2.

Validation

• NuGet Trusted Publishing completed successfully for the aligned package set.
• Release verification passed formatting, Release build, strict analyzers, 867 tests, package creation, and metadata validation.
• Windows, Linux, macOS, package-smoke, coverage, schema guardrails, docs, and CodeQL checks passed.

Highlights

• Added optional Fluent localization through two new packages:
  • IWF.TeleFlow.Framework.I18n for per-update locale resolution;
  • IWF.TeleFlow.Framework.I18n.Fluent for startup-loaded Linguini catalogs, Fluent terms, attributes, plurals, NUMBER, and DATETIME.
• Added plain, Telegram HTML, and Telegram MarkdownV2 localization modes with automatic escaping of dynamic arguments, typed formatted fragments, and custom emoji composition.
• Added TelegramHtml and TelegramMarkdownV2 builders and public escaping helpers for safe dynamic text composition.
• Clarified sender semantics with [FromUser], [FromBot], and [SenderChatType], including callback support and explicit user/bot ID allowlists.
• Exact and template command routes now match canonically equivalent Unicode input while preserving raw text and explicit regex semantics.
• Expanded current-update identity and diagnostics across Telegram Bot API 10.2 update families.

Breaking changes

• Replace [FromBot(false)] with parameterless [FromUser].
• [FromUser(userId)] now accepts only non-bot users. Use [FromBot(botId)] for bot accounts.
• TelegramChatType.Sender was removed because it is not a valid Telegram Chat.type. Use [SenderChatType(...)] with the actual sender-chat type.

Upgrade

Update every TeleFlow package used by the application to 1.0.0-alpha.13 together. Applications using Fluent localization normally install only the Fluent adapter; it brings the base i18n package transitively.

dotnet add package IWF.TeleFlow.Framework.LongPolling --version 1.0.0-alpha.13
dotnet add package IWF.TeleFlow.Generators --version 1.0.0-alpha.13
dotnet add package IWF.TeleFlow.Framework.I18n.Fluent --version 1.0.0-alpha.13

This release remains aligned with Telegram Bot API 10.2.

Validation

• NuGet Trusted Publishing completed successfully for the aligned 15-package release set.
• Release verification passed formatting, Release build, strict analyzers, the full test suite, package smoke tests, package creation, and metadata validation.
• New i18n package dependencies and symbol package outputs were inspected before publication.

Highlights

• Added high-level helpers for Telegram ephemeral messages and command registration:
  • BotCommands.Create(...) and BotCommands.Ephemeral(...);
  • message, callback, and client APIs for ephemeral delivery and dedicated edit/delete operations.
• Command routing is now deterministic when prefixes overlap: the longest prefix wins regardless of configuration order.
• Mention-qualified commands now reject commands addressed to another bot. Standard long-polling and webhook applications resolve and cache bot identity once at startup when BotUsername is not configured.
• Automatic callback-answer failures now participate in the existing [Error] pipeline. A handled error acknowledges the update; an unhandled error remains visible and unacknowledged.
• Long-polling lifecycle events are available at Information without enabling debug timing work. EN/RU documentation now defines the full update failure and acknowledgement contract.

Upgrade

Update all TeleFlow packages to the same 1.0.0-alpha.12 version. Applications that use mention-qualified commands through a custom/direct update source should configure BotUsername explicitly.

dotnet add package IWF.TeleFlow.Framework.LongPolling --prerelease
dotnet add package IWF.TeleFlow.Generators --prerelease
dotnet add package IWF.TeleFlow.Storage.Memory --prerelease

Validation

• NuGet Publish verification and publication completed successfully.
• Tag-based release verification completed successfully.
• Release verification includes formatting, Release build, strict analyzers, 771/771 tests, package creation, and package metadata validation.

Added

• Added TelegramBotApiEnvironment to configure production or Telegram Bot API test-environment requests through both AddTelegramClient(...) and AddTelegramBot(...).
• Added test-environment endpoint construction for all outgoing Bot API methods, including custom root BaseUrl configurations.

Changed

• Documented the separate Telegram test-account and test-bot credential requirement, the test endpoint path, and the current payment-update boundary.

Added

• Added CI guardrails for generated Telegram schema/client updates, requiring changelog acknowledgement and validating Telegram Bot API manifest, badge, and generated header consistency.

Changed

• Updated the generated Telegram schema and client surface to Telegram Bot API 10.2.

Fixed

• Fixed the CallbackQueryActions.AnswerAsync overload that accepted callback text and could recurse instead of sending the callback answer.
• Fixed prefix-less short command routes so ordinary text beginning with the same word does not trigger the command.

This alpha focuses on Telegram client response execution internals: clearer request execution stages and less JSON rematerialization on successful Bot API responses.

Changed

• Split TelegramRequestExecutor request processing into explicit send, parse, retry-after, success deserialization, API failure, and decode failure stages.
• Telegram response envelopes are now parsed from UTF-8 response bytes instead of first materializing the whole HTTP body as a string.
• Successful Telegram response result payloads are now deserialized from the parsed JsonElement instead of using GetRawText() and deserializing a second JSON string.
• HttpClientTelegramTransport now reads Telegram response bodies as bytes and passes owned response buffers into the client pipeline.
• Custom transport documentation now describes the byte-based response body contract in English and Russian.

Fixed

• Request diagnostics, retry-after handling, decode failure mapping, API failure mapping, cancellation, and getUpdates diagnostic suppression now have more focused regression coverage.
• Documentation home page example spacing was adjusted after the alpha.8 docs site update.

Breaking Changes

• TelegramTransportResponse.Body changed from string to ReadOnlyMemory<byte>.
  Existing custom transports can still construct responses from string, but code that reads Body directly must decode the UTF-8 bytes explicitly.

NuGet

• https://www.nuget.org/packages/IWF.TeleFlow.Framework.LongPolling/1.0.0-alpha.9
• https://www.nuget.org/packages/IWF.TeleFlow.Telegram/1.0.0-alpha.9
• https://www.nuget.org/packages/IWF.TeleFlow.Generators/1.0.0-alpha.9

This alpha focuses on production diagnostics, bounded Telegram retry-after handling, scoped current-update access, state storage key isolation, and explicit command prefix routing.

Added

• Added TelegramRetryAfterPolicy for bounded automatic handling of Telegram 429 retry_after responses.
• Added IUpdateContextAccessor for scoped access to the current transport-agnostic update during framework processing.
• Added ITelegramCurrentUpdateAccessor for scoped access to the current Telegram update, user, chat, message, callback query, chat member update, and state key.
• Added runtime dependency validation for handler, error handler, and custom filter service parameters.
• Added state storage key isolation contracts through IStateStorageKeyBuilder, DefaultStateStorageKeyBuilder, StateStorageKeyPart, and StateKeyDefaults.
• Added explicit state key customization helpers for production storage providers and multi-bot applications.
• Added CommandPrefixMode for [Command], [CommandTemplate], and [CommandRegex] routes.
• Added safe diagnostics for filter rejections, webhook invalid secret/payload handling, webhook update failures, and Telegram request failure exception types.

Changed

• Telegram request execution now retries only bounded short retry_after responses by default and throws TelegramRetryAfterException when the retry policy refuses to wait.
• Long polling startup delivery guidance now recommends an explicit startup task calling DeleteWebhookAsync(dropPendingUpdates: true) instead of hiding destructive delivery behavior in long polling options.
• State storage keys now have a documented, escaped, partition-aware format that storage providers can share consistently.
• Generated handler metadata now carries command prefix mode when a route opts into non-default command prefix behavior.
• Framework update rate limiting now uses explicit accept/reject decisions instead of exception-based throttling.
• Handler, error-handler, and filter dependencies now fail during runtime validation with targeted configuration errors instead of failing later during update handling where possible.
• Documentation now covers retry-after defaults, scoped current-update accessors, middleware/service lifetimes, state key customization, rate-limit decision behavior, and logging privacy rules.

Breaking Changes

• IUpdateRateLimiter.WaitAsync(...) was replaced with IUpdateRateLimiter.CheckAsync(...), returning UpdateRateLimitDecision.
• Custom update rate limiters must return UpdateRateLimitDecision.Accepted or UpdateRateLimitDecision.Rejected(...) instead of relying on exceptions for normal rejection.

This alpha focuses on typed callback data hardening: compile-time callback data codecs, clearer stale callback diagnostics, and validation before the 1.0.0 stabilization line.

Added

• Source-generated callback data codecs for [CallbackData] payloads when IWF.TeleFlow.Generators is installed.
• Generated callback packing, matching, and unpacking for typed inline keyboard payloads and typed callback routes.
• Warning diagnostics for compact typed callback data that matches a typed route shape but cannot be decoded.
• English and Russian documentation for stale callback buttons, raw callback fallbacks, and callback payload versioning guidance.

Changed

• Default typed callback serialization now prefers generated codecs and falls back to runtime metadata only when generated metadata is unavailable.
• Malformed compact typed callback data is treated as an unmatched typed route after a warning, allowing raw callback fallback handlers to answer old or stale buttons.
• Generated enum callback fields now decode through explicit validation instead of surfacing low-level enum parse failures.

Fixed

• Oversized [CallbackData] prefixes are reported by analyzer/runtime validation instead of failing later during keyboard packing.
• Stale compact typed callback payloads no longer look like random handler failures.

Closed

• #103
• #32