feat: SendChecklist and EditMessageChecklist

Checklists (Bot API todo lists) sent/edited on behalf of a connected business
account. InputChecklist / InputChecklistTask map to tg.InputMediaTodo
(TodoList/TodoItem); title and task text resolve through a new textWithEntities
helper honoring parse mode or explicit entities. SendChecklist reuses the
business media-send path; EditMessageChecklist edits via a business-scoped raw
client (new businessRaw helper). Hermetic tests; lint clean.

Author: ernado

business.go

@@ -116,6 +116,13 @@ func (b *Bot) businessSender(connectionID string) *message.Sender {
 	return message.NewSender(tg.NewClient(businessInvoker{inner: b.invoker, connectionID: connectionID}))
 }
 
+// businessRaw returns a raw *tg.Client whose every RPC is forwarded on behalf of
+// the business account identified by connectionID. It must not be used for
+// uploads (see businessInvoker).
+func (b *Bot) businessRaw(connectionID string) *tg.Client {
+	return tg.NewClient(businessInvoker{inner: b.invoker, connectionID: connectionID})
+}
+
 // GetBusinessConnection returns information about the connection of the bot with
 // a business account by the connection id received in updates.
 func (b *Bot) GetBusinessConnection(ctx context.Context, businessConnectionID string) (*BusinessConnection, error) {

checklist.go

@@ -0,0 +1,138 @@
+package botapi
+
+import (
+	"context"
+
+	"github.com/gotd/td/telegram/message"
+	"github.com/gotd/td/telegram/message/styling"
+	"github.com/gotd/td/tg"
+)
+
+// InputChecklistTask describes a task to add to a checklist on creation or edit.
+type InputChecklistTask struct {
+	// ID is the unique identifier of the task, positive and unique among the
+	// tasks of the checklist.
+	ID int
+	// Text is the task text, 1-100 characters after entities parsing.
+	Text string
+	// ParseMode is the formatting mode for Text.
+	ParseMode ParseMode
+	// TextEntities are explicit entities; they take precedence over ParseMode.
+	TextEntities []MessageEntity
+}
+
+// InputChecklist describes a checklist to create or replace.
+type InputChecklist struct {
+	// Title is the checklist title, 1-255 characters after entities parsing.
+	Title string
+	// ParseMode is the formatting mode for Title.
+	ParseMode ParseMode
+	// TitleEntities are explicit title entities; they take precedence over
+	// ParseMode.
+	TitleEntities []MessageEntity
+	// Tasks are the checklist tasks, 1-30 items.
+	Tasks []InputChecklistTask
+	// OthersCanAddTasks allows other users to add tasks to the checklist.
+	OthersCanAddTasks bool
+	// OthersCanMarkTasksAsDone allows other users to mark tasks as done or undone.
+	OthersCanMarkTasksAsDone bool
+}
+
+// textWithEntities resolves text plus a parse mode or explicit entities into the
+// MTProto TextWithEntities shape. Explicit entities take precedence.
+func (b *Bot) textWithEntities(ctx context.Context, text string, mode ParseMode, explicit []MessageEntity) (tg.TextWithEntities, error) {
+	if len(explicit) > 0 {
+		return tg.TextWithEntities{Text: text, Entities: entitiesToTg(explicit)}, nil
+	}
+
+	msg, entities, err := b.styledMessage(ctx, text, mode)
+	if err != nil {
+		return tg.TextWithEntities{}, err
+	}
+
+	return tg.TextWithEntities{Text: msg, Entities: entities}, nil
+}
+
+// checklistMedia converts an InputChecklist into MTProto todo-list media.
+func (b *Bot) checklistMedia(ctx context.Context, c InputChecklist) (*tg.InputMediaTodo, error) {
+	if len(c.Tasks) == 0 {
+		return nil, &Error{Code: 400, Description: "Bad Request: checklist must include at least one task"}
+	}
+
+	title, err := b.textWithEntities(ctx, c.Title, c.ParseMode, c.TitleEntities)
+	if err != nil {
+		return nil, err
+	}
+
+	list := make([]tg.TodoItem, len(c.Tasks))
+
+	for i, task := range c.Tasks {
+		taskTitle, err := b.textWithEntities(ctx, task.Text, task.ParseMode, task.TextEntities)
+		if err != nil {
+			return nil, err
+		}
+
+		list[i] = tg.TodoItem{ID: task.ID, Title: taskTitle}
+	}
+
+	return &tg.InputMediaTodo{Todo: tg.TodoList{
+		OthersCanAppend:   c.OthersCanAddTasks,
+		OthersCanComplete: c.OthersCanMarkTasksAsDone,
+		Title:             title,
+		List:              list,
+	}}, nil
+}
+
+// SendChecklist sends a checklist on behalf of a connected business account.
+func (b *Bot) SendChecklist(
+	ctx context.Context, businessConnectionID string, chat ChatID, checklist InputChecklist, opts ...SendOption,
+) (*Message, error) {
+	opts = append([]SendOption{WithBusinessConnection(businessConnectionID)}, opts...)
+
+	return b.sendResolvedMedia(ctx, chat, "", func(ctx context.Context, _ []styling.StyledTextOption) (message.MediaOption, error) {
+		todo, err := b.checklistMedia(ctx, checklist)
+		if err != nil {
+			return nil, err
+		}
+
+		return message.Media(todo), nil
+	}, opts...)
+}
+
+// EditMessageChecklist replaces the checklist in a message sent on behalf of a
+// connected business account.
+func (b *Bot) EditMessageChecklist(
+	ctx context.Context, businessConnectionID string, chat ChatID, messageID int, checklist InputChecklist, opts ...SendOption,
+) (*Message, error) {
+	var cfg sendConfig
+
+	for _, o := range opts {
+		o(&cfg)
+	}
+
+	peer, err := b.resolveInputPeer(ctx, chat)
+	if err != nil {
+		return nil, err
+	}
+
+	todo, err := b.checklistMedia(ctx, checklist)
+	if err != nil {
+		return nil, err
+	}
+
+	req := &tg.MessagesEditMessageRequest{Peer: peer, ID: messageID}
+	req.SetMedia(todo)
+
+	if cfg.markup != nil {
+		mkp, err := replyMarkupToTg(cfg.markup)
+		if err != nil {
+			return nil, err
+		}
+
+		req.SetReplyMarkup(mkp)
+	}
+
+	resp, err := b.businessRaw(businessConnectionID).MessagesEditMessage(ctx, req)
+
+	return b.sentMessage(ctx, peer, resp, err)
+}

checklist_test.go

@@ -0,0 +1,99 @@
+package botapi
+
+import (
+	"context"
+	"testing"
+
+	"github.com/gotd/td/tg"
+)
+
+func sampleChecklist() InputChecklist {
+	return InputChecklist{
+		Title:             "Groceries",
+		Tasks:             []InputChecklistTask{{ID: 1, Text: "Milk"}, {ID: 2, Text: "Bread"}},
+		OthersCanAddTasks: true,
+	}
+}
+
+func TestSendChecklist(t *testing.T) {
+	inv := newMockInvoker()
+	inv.reply(tg.InvokeWithBusinessConnectionRequestTypeID, businessSendReply())
+
+	b := newMockBot(inv)
+
+	if _, err := b.SendChecklist(context.Background(), "bc1", userRef(10, 20), sampleChecklist()); err != nil {
+		t.Fatalf("SendChecklist: %v", err)
+	}
+
+	wrapper := tg.InvokeWithBusinessConnectionRequest{Query: &tg.MessagesSendMediaRequest{}}
+
+	inv.decode(t, tg.InvokeWithBusinessConnectionRequestTypeID, &wrapper)
+
+	if wrapper.ConnectionID != "bc1" {
+		t.Fatalf("connection id = %q", wrapper.ConnectionID)
+	}
+
+	sm, ok := wrapper.Query.(*tg.MessagesSendMediaRequest)
+	if !ok {
+		t.Fatalf("query = %#v", wrapper.Query)
+	}
+
+	todo, ok := sm.Media.(*tg.InputMediaTodo)
+	if !ok {
+		t.Fatalf("media = %#v, want todo", sm.Media)
+	}
+
+	if todo.Todo.Title.Text != "Groceries" || len(todo.Todo.List) != 2 || !todo.Todo.OthersCanAppend {
+		t.Fatalf("todo = %#v", todo.Todo)
+	}
+
+	if todo.Todo.List[0].ID != 1 || todo.Todo.List[0].Title.Text != "Milk" {
+		t.Fatalf("task 0 = %#v", todo.Todo.List[0])
+	}
+}
+
+func TestEditMessageChecklist(t *testing.T) {
+	inv := newMockInvoker()
+	inv.reply(tg.InvokeWithBusinessConnectionRequestTypeID, businessSendReply())
+
+	b := newMockBot(inv)
+
+	if _, err := b.EditMessageChecklist(context.Background(), "bc2", userRef(10, 20), 5, sampleChecklist()); err != nil {
+		t.Fatalf("EditMessageChecklist: %v", err)
+	}
+
+	wrapper := tg.InvokeWithBusinessConnectionRequest{Query: &tg.MessagesEditMessageRequest{}}
+
+	inv.decode(t, tg.InvokeWithBusinessConnectionRequestTypeID, &wrapper)
+
+	if wrapper.ConnectionID != "bc2" {
+		t.Fatalf("connection id = %q", wrapper.ConnectionID)
+	}
+
+	em, ok := wrapper.Query.(*tg.MessagesEditMessageRequest)
+	if !ok {
+		t.Fatalf("query = %#v", wrapper.Query)
+	}
+
+	if em.ID != 5 {
+		t.Fatalf("message id = %d", em.ID)
+	}
+
+	media, ok := em.GetMedia()
+	if !ok {
+		t.Fatal("edit should set media")
+	}
+
+	if _, ok := media.(*tg.InputMediaTodo); !ok {
+		t.Fatalf("media = %#v, want todo", media)
+	}
+}
+
+func TestChecklistEmptyTasks(t *testing.T) {
+	inv := newMockInvoker()
+
+	if _, err := newMockBot(inv).SendChecklist(context.Background(), "bc1", userRef(10, 20),
+		InputChecklist{Title: "x"}); err == nil {
+		t.Fatal("expected error for checklist without tasks")
+	}
+}