go-telegram/CHANGELOG.md

Changelog

All notable changes to this project will be documented in this file. The format follows Keep a Changelog and this project adheres to Semantic Versioning.

[Unreleased]

[1.0.0] - 2026-05-09

Initial public release. Built against Telegram Bot API v10.0 (176 methods, 301 types).

Library surface

• client.Bot with pluggable HTTPDoer, Codec (default github.com/goccy/go-json), and Logger interfaces.
• Generic client.Call[Req, Resp] and client.CallRaw[Req] helpers — every API method funnels through one of these.
• client.RetryDoer middleware — exponential backoff with jitter; honours Telegram's retry_after; replays request bodies across attempts. Configurable via RetryOption functions (WithMaxAttempts, WithBase, WithMax, WithFactor, WithJitter).
• Typed errors: *APIError (sentinel-mapped: ErrUnauthorized, ErrForbidden, ErrTooManyRequests, ErrChatNotFound, ErrMessageNotModified, ErrBadRequest, ErrUserNotFound, ErrMessageNotFound), *NetworkError, *ParseError. Bot tokens redacted from error messages.

Update delivery

• transport.LongPoller — getUpdates loop with ExponentialBackoff, retry-after honouring, graceful shutdown via Stop.
• transport.WebhookServer — http.Handler + ListenAndServe; secret-token verification (constant-time); 1 MiB body cap; in-flight handler tracking via WaitGroup.

Dispatcher

• Generic dispatch.Handler[T] and dispatch.Middleware[T].
• 21 typed handler registrations: OnCommand, OnText, OnCallback, OnInlineQuery, OnEditedMessage, OnChannelPost, OnEditedChannelPost, OnMyChatMember, OnChatMember, OnChatJoinRequest, OnPreCheckoutQuery, OnShippingQuery, OnPoll, OnPollAnswer, OnChosenInlineResult, OnMessageReaction, OnMessageReactionCount, OnChatBoost, OnRemovedChatBoost, OnBusinessConnection, OnPurchasedPaidMedia. Filter variants available for message, callback, inline-query, chat-member, chat-join-request, and pre-checkout-query types.
• Composable filters in dispatch/filters/{message,callback,inline,chatmember,chatjoinrequest,precheckoutquery} packages with And/Or/Not/All/Any combinators and 20+ filter helpers.
• dispatch/conversation — multi-step state machines with Storage interface (MemoryStorage default), pluggable KeyStrategy (KeyByUser, KeyByChat, KeyByUserAndChat), entry/state/exit/fallback steps, AllowReEntry. Next(state) and End() sentinel errors drive transitions. Conversation.Dispatch integrates as middleware via router.Use.
• Per-update goroutine pool (default 50; configurable via WithMaxConcurrency). Pass 0 for serial dispatch.
• Handler groups with EndGroups/ContinueGroups flow control.
• NamedHandlers[T] for runtime registration and replacement.
• Panic-recovery middleware + automatic handler-error logging registered by default.

Generated API

• Full Bot API v10.0 surface in api/*.gen.go — 176 methods, 301 types, regenerated from a committed HTML snapshot of core.telegram.org/bots/api.
• Strongly typed unions: ChatID (Integer-or-String), *InputFile (InputFile-or-String), MessageOrBool (Message-or-True returns).
• 13 discriminated unions with auto-decode: ChatMember, MessageOrigin, ReactionType, PaidMedia, BackgroundType, BackgroundFill, ChatBoostSource, RevenueWithdrawalState, TransactionPartner, MenuButton, OwnedGift, StoryAreaType, MaybeInaccessibleMessage. Parent structs containing union-typed fields auto-decode via generated UnmarshalJSON.
• Sealed-interface return types use client.CallRaw + Unmarshal<Name> dispatch (e.g., GetChatMember returns ChatMember interface, decoded into the correct concrete variant).

Runtime helpers

• api.MeCache — concurrent-safe getMe cache; zero-value safe.
• api.DownloadFile / api.DownloadFileByPath — fetch file contents from the Telegram CDN.
• (*Message).GetSender() — unifies From, SenderChat, and anonymous-admin fields into a *Sender.

Codegen pipeline (cmd/scrape, cmd/genapi, cmd/audit)

• Two-stage codegen: HTML → IR (internal/spec/api.json) → Go.
• internal/spec/overrides.json pins specific method returns/field types when scraper regex does not match a particular doc phrasing.
• cmd/audit reports any-typed fields, fallback bool returns, and signature drift vs HEAD's IR. Exit codes: 0 clean, 1 fallback, 2 drift, 3 invalid.
• make regen is self-verifying: clean → scrape → audit → emit (code + 1428 tests) → run tests.
• Auto-generated tests cover 8 scenarios per method (1428 total): Success, APIError 429, NetworkError, ParseError, ContextCanceled, MissingRequiredFields (400 + ErrBadRequest), Forbidden (403 + ErrForbidden), ServerError (500 + IsRetryable).

Tooling

• .github/workflows/ci.yml — Go matrix 1.23/1.24, vet, staticcheck, govulncheck, gosec, race tests, codegen-clean check, audit + drift detection.
• .github/workflows/regen.yml — weekly cron + workflow_dispatch; scrapes live API, regenerates, runs tests, opens auto-PR with audit summary in body.
• .github/workflows/release.yml — semver-generator-driven version bump; dual tagging (library SemVer + bot-api-v<X.Y> marker); GoReleaser.
• .goreleaser.yaml — ships tg-scrape, tg-genapi, tg-audit binaries for Linux/macOS/Windows × amd64/arm64.

Examples (14)

echo, webhook, callback, conversation, files, inline, middleware, stateful, welcome, moderation, polls, payments, pagination, admin.