Initial release of go-telegram

A fully-generated, strongly-typed Go client for the Telegram Bot API.

* 176 methods + 301 types generated from Bot API v10.0
* 1408 auto-generated tests (8 scenarios per method)
* Typed unions throughout — no 'any' in the public surface
* Pluggable HTTP transport and JSON codec (default goccy/go-json)
* Built-in retry middleware honouring Telegram's retry_after
* Generic dispatcher with filters and conversation handlers
* Self-verifying codegen pipeline (regen → audit → emit → run tests)
* 14 example bots covering common patterns

examples/conversation/README.md

@@ -0,0 +1,10 @@
+# conversation
+
+Multi-step conversation flow demonstrating `dispatch/conversation`. Send `/newbot` to start; reply with a name then a description. Send `/cancel` at any point to abort.
+
+## Run
+
+```bash
+export TELEGRAM_BOT_TOKEN=...
+go run ./examples/conversation
+```

examples/conversation/handlers.go

@@ -0,0 +1,75 @@
+package main
+
+import (
+	"github.com/lukaszraczylo/go-telegram/api"
+	"github.com/lukaszraczylo/go-telegram/client"
+	"github.com/lukaszraczylo/go-telegram/dispatch"
+	"github.com/lukaszraczylo/go-telegram/dispatch/conversation"
+	msgfilter "github.com/lukaszraczylo/go-telegram/dispatch/filters/message"
+)
+
+// onMsg lifts a Filter[*api.Message] into a Filter[*api.Update].
+func onMsg(f dispatch.Filter[*api.Message]) dispatch.Filter[*api.Update] {
+	return func(u *api.Update) bool { return u.Message != nil && f(u.Message) }
+}
+
+// notCmd matches message updates that are NOT a bot command.
+var notCmd = onMsg(msgfilter.AnyCommand().Not())
+
+// buildConv constructs the /newbot conversation. Accepts an optional Storage
+// so tests can inject MemoryStorage for isolation; pass nil for the default.
+func buildConv(storage conversation.Storage) *conversation.Conversation {
+	conv := &conversation.Conversation{
+		Storage: storage,
+		EntryPoints: []conversation.Step{{
+			Filter: onMsg(msgfilter.Command("/newbot")),
+			Handler: func(c *dispatch.Context, u *api.Update) error {
+				_, _ = api.SendMessage(c.Ctx, c.Bot, &api.SendMessageParams{
+					ChatID: api.ChatIDFromInt(u.Message.Chat.ID),
+					Text:   "What should the bot's name be?",
+				})
+				return conversation.Next("await_name")
+			},
+		}},
+		States: map[conversation.State][]conversation.Step{
+			"await_name": {{
+				Filter: notCmd,
+				Handler: func(c *dispatch.Context, u *api.Update) error {
+					_, _ = api.SendMessage(c.Ctx, c.Bot, &api.SendMessageParams{
+						ChatID: api.ChatIDFromInt(u.Message.Chat.ID),
+						Text:   "Got it! What's the description?",
+					})
+					return conversation.Next("await_desc")
+				},
+			}},
+			"await_desc": {{
+				Filter: notCmd,
+				Handler: func(c *dispatch.Context, u *api.Update) error {
+					_, _ = api.SendMessage(c.Ctx, c.Bot, &api.SendMessageParams{
+						ChatID: api.ChatIDFromInt(u.Message.Chat.ID),
+						Text:   "Done! Your bot has been configured.",
+					})
+					return conversation.End()
+				},
+			}},
+		},
+		Exits: []conversation.Step{{
+			Filter: onMsg(msgfilter.Command("/cancel")),
+			Handler: func(c *dispatch.Context, u *api.Update) error {
+				_, _ = api.SendMessage(c.Ctx, c.Bot, &api.SendMessageParams{
+					ChatID: api.ChatIDFromInt(u.Message.Chat.ID),
+					Text:   "Cancelled.",
+				})
+				return conversation.End()
+			},
+		}},
+	}
+	return conv
+}
+
+// register wires the conversation middleware onto the router.
+func register(r *dispatch.Router, bot *client.Bot) {
+	_ = bot // bot available for future handlers if needed
+	conv := buildConv(nil)
+	r.Use(conv.Dispatch)
+}

examples/conversation/handlers_test.go

@@ -0,0 +1,133 @@
+package main
+
+import (
+	"bytes"
+	"context"
+	"io"
+	"net/http"
+	"testing"
+
+	"github.com/lukaszraczylo/go-telegram/api"
+	"github.com/lukaszraczylo/go-telegram/client"
+	"github.com/lukaszraczylo/go-telegram/dispatch"
+	"github.com/lukaszraczylo/go-telegram/dispatch/conversation"
+	"github.com/stretchr/testify/mock"
+	"github.com/stretchr/testify/require"
+)
+
+// mockDoer satisfies client.HTTPDoer.
+type mockDoer struct{ mock.Mock }
+
+func (m *mockDoer) Do(r *http.Request) (*http.Response, error) {
+	args := m.Called(r)
+	if v := args.Get(0); v != nil {
+		return v.(*http.Response), args.Error(1)
+	}
+	return nil, args.Error(1)
+}
+
+func anyResp() *http.Response {
+	return &http.Response{
+		StatusCode: 200,
+		Body:       io.NopCloser(bytes.NewBufferString(`{"ok":true,"result":{"message_id":1,"date":0,"chat":{"id":1,"type":"private"}}}`)),
+		Header:     http.Header{"Content-Type": []string{"application/json"}},
+	}
+}
+
+// msgUpd builds a message update with the given user/chat/text.
+func msgUpd(userID, chatID int64, text string) api.Update {
+	entities := []api.MessageEntity{}
+	if len(text) > 0 && text[0] == '/' {
+		end := len(text)
+		for i, r := range text {
+			if r == ' ' {
+				end = i
+				break
+			}
+		}
+		entities = append(entities, api.MessageEntity{
+			Type:   string(api.EntityBotCommand),
+			Offset: 0,
+			Length: int64(end),
+		})
+	}
+	return api.Update{
+		UpdateID: 1,
+		Message: &api.Message{
+			MessageID: 1,
+			From:      &api.User{ID: userID},
+			Chat:      api.Chat{ID: chatID, Type: string(api.ChatTypePrivate)},
+			Text:      text,
+			Entities:  entities,
+		},
+	}
+}
+
+func makeCtx(bot *client.Bot, u *api.Update) *dispatch.Context {
+	return dispatch.NewContext(context.Background(), bot, u)
+}
+
+// allowAny mocks unlimited sendMessage calls.
+func allowAny(m *mockDoer) {
+	m.On("Do", mock.Anything).Return(anyResp(), nil)
+}
+
+func TestConversation_NewBot_AsksName(t *testing.T) {
+	m := &mockDoer{}
+	allowAny(m)
+	bot := client.New("test:token", client.WithHTTPClient(m))
+
+	store := conversation.NewMemoryStorage()
+	conv := buildConv(store)
+	mw := conv.Dispatch(func(c *dispatch.Context, u *api.Update) error { return nil })
+
+	u := msgUpd(42, 1, "/newbot")
+	require.NoError(t, mw(makeCtx(bot, &u), &u))
+
+	state, err := store.Get(context.Background(), "uc:1:42")
+	require.NoError(t, err)
+	require.Equal(t, conversation.State("await_name"), state)
+}
+
+func TestConversation_NewBot_StoresName_AsksDesc(t *testing.T) {
+	m := &mockDoer{}
+	allowAny(m)
+	bot := client.New("test:token", client.WithHTTPClient(m))
+
+	store := conversation.NewMemoryStorage()
+	conv := buildConv(store)
+	mw := conv.Dispatch(func(c *dispatch.Context, u *api.Update) error { return nil })
+
+	// Enter conversation.
+	u1 := msgUpd(42, 1, "/newbot")
+	require.NoError(t, mw(makeCtx(bot, &u1), &u1))
+
+	// Reply with name — should advance to await_desc.
+	u2 := msgUpd(42, 1, "MyBot")
+	require.NoError(t, mw(makeCtx(bot, &u2), &u2))
+
+	state, err := store.Get(context.Background(), "uc:1:42")
+	require.NoError(t, err)
+	require.Equal(t, conversation.State("await_desc"), state)
+}
+
+func TestConversation_Cancel_EndsConversation(t *testing.T) {
+	m := &mockDoer{}
+	allowAny(m)
+	bot := client.New("test:token", client.WithHTTPClient(m))
+
+	store := conversation.NewMemoryStorage()
+	conv := buildConv(store)
+	mw := conv.Dispatch(func(c *dispatch.Context, u *api.Update) error { return nil })
+
+	// Enter conversation.
+	u1 := msgUpd(42, 1, "/newbot")
+	require.NoError(t, mw(makeCtx(bot, &u1), &u1))
+
+	// Cancel mid-flow.
+	u2 := msgUpd(42, 1, "/cancel")
+	require.NoError(t, mw(makeCtx(bot, &u2), &u2))
+
+	_, err := store.Get(context.Background(), "uc:1:42")
+	require.ErrorIs(t, err, conversation.ErrKeyNotFound, "cancel must clear state")
+}

examples/conversation/main.go

@@ -0,0 +1,37 @@
+// Package main demonstrates a /newbot-style conversation flow using
+// dispatch/conversation.
+//
+//	TELEGRAM_BOT_TOKEN=xxx go run ./examples/conversation
+package main
+
+import (
+	"context"
+	"log"
+	"os"
+	"os/signal"
+	"syscall"
+
+	"github.com/lukaszraczylo/go-telegram/client"
+	"github.com/lukaszraczylo/go-telegram/dispatch"
+	"github.com/lukaszraczylo/go-telegram/transport"
+)
+
+func main() {
+	token := os.Getenv("TELEGRAM_BOT_TOKEN")
+	if token == "" {
+		log.Fatal("TELEGRAM_BOT_TOKEN required")
+	}
+	ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
+	defer stop()
+
+	bot := client.New(token,
+		client.WithHTTPClient(client.NewRetryDoer(client.NewDefaultHTTPDoer())))
+
+	router := dispatch.New(bot)
+	register(router, bot)
+
+	poller := transport.NewLongPoller(bot)
+	if err := router.Run(ctx, poller); err != nil && err != context.Canceled {
+		log.Printf("router exited: %v", err)
+	}
+}