TeleFlow 1.0.0-alpha.8

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.

TeleFlow 1.0.0-alpha.7

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

TeleFlow 1.0.0-alpha.6

Summary

This alpha focuses on Microsoft.Extensions.Hosting integration, application lifecycle tasks, package graph naming stabilization, and release packaging hardening.

NuGet packages for 1.0.0-alpha.6 were published through the NuGet Trusted Publishing workflow and verified before this GitHub release.

Install

Handler-based long polling bot:

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

Optional Generic Host integration:

dotnet add package IWF.TeleFlow.Framework.Hosting --prerelease

Direct Telegram Bot API client:

dotnet add package IWF.TeleFlow.Telegram --prerelease

Added

• Optional IWF.TeleFlow.Framework.Hosting package for running a configured TeleFlow application through Microsoft.Extensions.Hosting as an IHostedService.
• Application startup and shutdown task contracts with DI registration helpers.
• Lifecycle execution around update source startup and shutdown, including scoped task resolution, deterministic ordering, and failure propagation.

Changed

• Framework runtime package names were stabilized before 1.0.0:
  • IWF.TeleFlow.Core became IWF.TeleFlow.Framework.Core.
  • IWF.TeleFlow.Telegram.Framework became IWF.TeleFlow.Framework.
  • IWF.TeleFlow.Telegram.Framework.LongPolling became IWF.TeleFlow.Framework.LongPolling.
  • IWF.TeleFlow.Telegram.Framework.Webhooks became IWF.TeleFlow.Framework.Webhooks.
• Framework runtime namespaces now use TeleFlow.Framework.* instead of TeleFlow.Core.*.
• Documentation and package descriptions now separate recommended entry packages from dependency and advanced packages.
• Middleware options configuration is documented as normal .NET options configuration.
• Release verification now checks that its packaged project list stays aligned with package smoke tests.

Fixed

• Release verification now includes IWF.TeleFlow.Framework.Hosting, preventing a publish run from accidentally omitting the hosting package.

Deprecated

The old alpha package IDs were deprecated on NuGet with replacement package guidance:

• IWF.TeleFlow.Core -> IWF.TeleFlow.Framework.Core.
• IWF.TeleFlow.Telegram.Framework -> IWF.TeleFlow.Framework.
• IWF.TeleFlow.Telegram.Framework.LongPolling -> IWF.TeleFlow.Framework.LongPolling.
• IWF.TeleFlow.Telegram.Framework.Webhooks -> IWF.TeleFlow.Framework.Webhooks.

Breaking Changes

• Applications using old alpha framework package IDs must migrate to the new IWF.TeleFlow.Framework.* package IDs.
• Applications using TeleFlow.Core.* namespaces must migrate to TeleFlow.Framework.* namespaces.

Validation

• NuGet Publish workflow completed successfully: https://github.com/IWFTech/TeleFlow/actions/runs/28522279727
• Release-preparation checks for the changelog PR passed on Windows, Linux, and macOS.
• A local smoke bot was built against the published 1.0.0-alpha.6 packages and manually checked through Telegram long polling.

TeleFlow 1.0.0-alpha.5

This alpha focuses on handler registration semantics, compile-time filter metadata, route dispatch indexing, and typed callback keyboard packing.

Added

• Parameterized custom filter attributes with generated metadata, constructor arguments, and named arguments.
• Generator diagnostics for handler methods that define state, role, chat member, or filter metadata without any route attribute.

Changed

• Handler route candidates are pre-indexed once and reused during dispatch to reduce repeated per-update scans.
• Generated assembly registration, explicit direct registration, and deprecated reflection assembly registration are now documented as separate contracts.
• Explicit handler and module registration semantics are documented for manual registration without generated metadata.
• Typed inline keyboard callback payloads now pack through [CallbackData] metadata with InlineKeyboardBuilder.Build(), while raw callback strings are preserved exactly.
• Callback keyboard serialization ownership is explicit: custom ICallbackDataSerializer remains available for advanced callback serialization and route deserialization, while typed keyboard buttons use callback metadata directly.

Fixed

• Filter-only handler methods are reported at build time instead of being silently ignored by generated registration.

Deprecated

• Reflection-based assembly handler registration is deprecated in favor of generated registration or explicit direct registration.

Breaking Changes

• InlineKeyboardBuilder.Build(ICallbackDataSerializer) was removed. Use InlineKeyboardBuilder.Build() and pass the resulting native InlineKeyboardMarkup to Telegram methods or message helpers.

NuGet

Published package version: 1.0.0-alpha.5.

Main package for long polling bots:

dotnet add package IWF.TeleFlow.Telegram.Framework.LongPolling --version 1.0.0-alpha.5 --prerelease

Validation

• NuGet Publish workflow completed successfully on main at 20c64fe.
• Release verification completed before publishing: restore, format, release build, strict analyzers, tests, and package validation.
• NuGet flat-container API reports 1.0.0-alpha.5 for all 12 TeleFlow packages.

TeleFlow 1.0.0-alpha.4

This alpha focuses on runtime hot-path reductions, scoped middleware lifetimes, explicit keyboard markup ownership, generated Bot API constants, and release workflow hardening.

Added

• Telegram announcement workflow for release, pull request, and issue notifications.
• Generated Bot API discriminator constants adoption for documented keyboard button styles.

Changed

• Update middleware is resolved from the per-update scope, so middleware can depend on scoped application services such as repositories.
• Inline keyboard creation now uses an explicit InlineKeyboardBuilder.Build() step that returns native InlineKeyboardMarkup.
• Handler timing details are collected only when debug logging is enabled.
• State hydration snapshot semantics were clarified after review, including how failed storage reads interact with cached update state.
• State data and wizard wrappers are created lazily per update.
• Telegram error handlers are pre-indexed for exception-path dispatch.
• Handler selection, filter evaluation, typed callback route misses, compact callback metadata lookup, and JSON-only request content building now avoid several avoidable runtime allocations or scans.
• Generated Telegram schema output was refreshed with grouped discriminator constants.
• Telegram announcement summaries were reformatted for clearer public issue, pull request, and release messages.
• GitHub Actions dependencies and NuGet symbol package publishing were hardened.

Fixed

• Scoped repositories and services can now be consumed from update middleware without singleton lifetime validation failures.
• Callback route candidate checks no longer use exception-driven no-match flow for typed callback payloads.
• JSON-only Telegram requests no longer recursively scan payload values when the request type cannot contain upload streams.
• Duplicate NuGet symbol package push behavior was removed from the publish workflow.

Breaking Changes

• Inline keyboard builders must be converted to native markup explicitly with .Build() before being passed to Telegram methods or message helpers.

Notes

• Final typed keyboard callback serialization ownership is intentionally not finalized in this alpha. The design work continues in 1.0.0-alpha.5.

TeleFlow 1.0.0-alpha.3

TeleFlow 1.0.0-alpha.3

This alpha focuses on framework trust, state consistency, package readability, and documentation polish.

Added

• XML documentation for public TeleFlow.Annotations APIs.
• Package verification that ensures IWF.TeleFlow.Annotations includes XML documentation in the NuGet package.
• Reusable state storage contract tests for current and future storage providers.
• GitHub Pages documentation site and benchmark documentation.

Changed

• ctx.State now caches the current state snapshot for the duration of one update, including the no-state null case.
• TeleFlow.Annotations source files are grouped by responsibility while the public TeleFlow.Annotations namespace remains stable.
• Documentation navigation, theme contrast, README badges, package onboarding, and quickstart examples were refined.

Fixed

• Repeated current-state reads in one update no longer cause repeated storage reads.
• State snapshot failure semantics are explicit: failed storage calls do not update the cached snapshot.
• Quickstart and command template examples were corrected for current handler registration usage.

Breaking Changes

• None.

NuGet

All IWF.TeleFlow.* packages are published as 1.0.0-alpha.3 on nuget.org.

TeleFlow 1.0.0-alpha.2

Public alpha release for the 1.0.0 line.

NuGet packages published as 1.0.0-alpha.2:

• IWF.TeleFlow.Telegram.Framework.LongPolling
• IWF.TeleFlow.Telegram.Framework.Webhooks
• IWF.TeleFlow.Telegram
• IWF.TeleFlow.Telegram.Client
• IWF.TeleFlow.Telegram.LongPolling
• IWF.TeleFlow.Telegram.Webhooks
• IWF.TeleFlow.Telegram.Framework
• IWF.TeleFlow.Telegram.Schema
• IWF.TeleFlow.Core
• IWF.TeleFlow.Annotations
• IWF.TeleFlow.Generators
• IWF.TeleFlow.Storage.Memory

Highlights:

• Improved NuGet package metadata and package descriptions.
• Updated README and documentation install commands for public alpha usage.
• Added clearer first-bot setup guidance for TELEFLOW_BOT_TOKEN.

Install example:

dotnet add package IWF.TeleFlow.Telegram.Framework.LongPolling --version 1.0.0-alpha.2
dotnet add package IWF.TeleFlow.Generators --version 1.0.0-alpha.2
dotnet add package IWF.TeleFlow.Storage.Memory --version 1.0.0-alpha.2

This is an alpha release. Public APIs may still change before 1.0.0.

TeleFlow 0.1.0-alpha.1

TeleFlow 0.1.0-alpha.1

First public alpha release of TeleFlow.

TeleFlow is an explicit Telegram Bot API framework for .NET / C# with generated Bot API client methods, attribute-based handlers, dependency injection, state management, callbacks, long polling, and webhook support.

Status

This is an alpha release.

The project is usable for testing, feedback, and early experiments, but public APIs may still change before v1.

Packages

NuGet packages are published under the IWF.TeleFlow.* prefix.

Main long polling package:

https://www.nuget.org/packages/IWF.TeleFlow.Telegram.Framework.LongPolling/0.1.0-alpha.1

Direct Telegram Bot API client:

https://www.nuget.org/packages/IWF.TeleFlow.Telegram/0.1.0-alpha.1

Generator package:

https://www.nuget.org/packages/IWF.TeleFlow.Generators/0.1.0-alpha.1

Memory storage package:

https://www.nuget.org/packages/IWF.TeleFlow.Storage.Memory/0.1.0-alpha.1

Highlights

• Telegram Bot API client with generated method extensions.
• Handler framework with attributes such as [Command], [Text], [Callback], [State], and media filters.
• Build-time generated handler metadata through IWF.TeleFlow.Generators.
• Dependency injection through Microsoft.Extensions.DependencyInjection.
• State, state data, and wizard-oriented APIs.
• Memory state storage package.
• Long polling and webhook framework adapters.
• Raw long polling and raw webhook packages.
• English and Russian documentation.
• No-network BenchmarkDotNet suite for framework/client comparisons.

Community

Telegram chat:
https://t.me/teleflow_chat

GitHub Issues:
https://github.com/IWFTech/TeleFlow/issues

Notes

This release is marked as a GitHub pre-release. Treat it as an early public alpha and pin exact package versions in test projects.