feat: add SendGift

Sends a gift (by id from GetAvailableGifts) to a user or channel chat via the
two-step Telegram Stars payment flow: payments.getPaymentForm with an
inputInvoiceStarGift, then payments.sendStarsForm with the returned form id.

Functional options cover the optional gift text (WithGiftText, with parse mode
via WithGiftParseMode or explicit WithGiftEntities) and pay-for-upgrade
(WithGiftPayForUpgrade). Text is resolved through the existing styledMessage /
entitiesToTg helpers into a TextWithEntities.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: ernado

send_gift.go

@@ -0,0 +1,114 @@
+package botapi
+
+import (
+	"context"
+	"strconv"
+
+	"github.com/gotd/td/tg"
+)
+
+// giftConfig holds the optional parameters of SendGift.
+type giftConfig struct {
+	text          string
+	parseMode     ParseMode
+	entities      []MessageEntity
+	payForUpgrade bool
+}
+
+// GiftOption customizes SendGift.
+type GiftOption func(*giftConfig)
+
+// WithGiftText attaches a text message to the gift.
+func WithGiftText(text string) GiftOption {
+	return func(c *giftConfig) { c.text = text }
+}
+
+// WithGiftParseMode sets the parse mode used for the gift text.
+func WithGiftParseMode(mode ParseMode) GiftOption {
+	return func(c *giftConfig) { c.parseMode = mode }
+}
+
+// WithGiftEntities sets explicit entities for the gift text, overriding the
+// parse mode.
+func WithGiftEntities(entities []MessageEntity) GiftOption {
+	return func(c *giftConfig) { c.entities = entities }
+}
+
+// WithGiftPayForUpgrade pays for the gift to be eligible for an upgrade to a
+// unique (collectible) gift by the receiver.
+func WithGiftPayForUpgrade() GiftOption {
+	return func(c *giftConfig) { c.payForUpgrade = true }
+}
+
+// SendGift sends a gift, identified by an id from GetAvailableGifts, to a user
+// or channel chat. The gift can't be converted to Telegram Stars by the
+// receiver.
+func (b *Bot) SendGift(ctx context.Context, target ChatID, giftID string, opts ...GiftOption) error {
+	var cfg giftConfig
+
+	for _, opt := range opts {
+		opt(&cfg)
+	}
+
+	id, err := strconv.ParseInt(giftID, 10, 64)
+	if err != nil {
+		return &Error{Code: 400, Description: "Bad Request: invalid gift_id"}
+	}
+
+	peer, err := b.resolveInputPeer(ctx, target)
+	if err != nil {
+		return err
+	}
+
+	invoice := &tg.InputInvoiceStarGift{
+		Peer:           peer,
+		GiftID:         id,
+		IncludeUpgrade: cfg.payForUpgrade,
+	}
+
+	if cfg.text != "" {
+		text, entities, err := b.giftMessage(ctx, cfg)
+		if err != nil {
+			return err
+		}
+
+		invoice.SetMessage(tg.TextWithEntities{Text: text, Entities: entities})
+	}
+
+	return b.payStarsForm(ctx, invoice)
+}
+
+// giftMessage resolves the gift text into a (text, entities) pair: explicit
+// entities take precedence over the parse mode.
+func (b *Bot) giftMessage(ctx context.Context, cfg giftConfig) (string, []tg.MessageEntityClass, error) {
+	if len(cfg.entities) > 0 {
+		return cfg.text, entitiesToTg(cfg.entities), nil
+	}
+
+	return b.styledMessage(ctx, cfg.text, cfg.parseMode)
+}
+
+// payStarsForm runs the two-step Telegram Stars payment flow for an invoice:
+// fetch the payment form, then submit it.
+func (b *Bot) payStarsForm(ctx context.Context, invoice tg.InputInvoiceClass) error {
+	form, err := b.raw.PaymentsGetPaymentForm(ctx, &tg.PaymentsGetPaymentFormRequest{
+		Invoice: invoice,
+	})
+	if err != nil {
+		return asAPIError(err)
+	}
+
+	stars, ok := form.(*tg.PaymentsPaymentFormStarGift)
+	if !ok {
+		return &Error{Code: 500, Description: "Internal Server Error: unexpected payment form"}
+	}
+
+	if _, err := b.raw.PaymentsSendStarsForm(ctx, &tg.PaymentsSendStarsFormRequest{
+		FormID:  stars.FormID,
+		Invoice: invoice,
+	}); err != nil {
+		return asAPIError(err)
+	}
+
+	return nil
+}

send_gift_test.go

@@ -0,0 +1,77 @@
+package botapi
+
+import (
+	"context"
+	"testing"
+
+	"github.com/gotd/td/tg"
+)
+
+func TestSendGift(t *testing.T) {
+	inv := newMockInvoker()
+	inv.reply(tg.PaymentsGetPaymentFormRequestTypeID, &tg.PaymentsPaymentFormStarGift{
+		FormID:  999,
+		Invoice: tg.Invoice{Currency: "XTR"},
+	})
+	inv.reply(tg.PaymentsSendStarsFormRequestTypeID, &tg.PaymentsPaymentResult{
+		Updates: &tg.Updates{},
+	})
+
+	bot := newMockBot(inv)
+
+	err := bot.SendGift(context.Background(), userRef(42, 7), "100",
+		WithGiftText("thanks!"), WithGiftPayForUpgrade())
+	if err != nil {
+		t.Fatalf("SendGift: %v", err)
+	}
+
+	var form tg.PaymentsGetPaymentFormRequest
+
+	inv.decode(t, tg.PaymentsGetPaymentFormRequestTypeID, &form)
+
+	invoice, ok := form.Invoice.(*tg.InputInvoiceStarGift)
+	if !ok {
+		t.Fatalf("invoice = %#v, want star gift", form.Invoice)
+	}
+
+	if invoice.GiftID != 100 {
+		t.Fatalf("gift id = %d, want 100", invoice.GiftID)
+	}
+
+	if !invoice.IncludeUpgrade {
+		t.Fatalf("include upgrade not set")
+	}
+
+	if invoice.Message.Text != "thanks!" {
+		t.Fatalf("message = %q", invoice.Message.Text)
+	}
+
+	if _, ok := invoice.Peer.(*tg.InputPeerUser); !ok {
+		t.Fatalf("peer = %#v, want user", invoice.Peer)
+	}
+
+	var send tg.PaymentsSendStarsFormRequest
+
+	inv.decode(t, tg.PaymentsSendStarsFormRequestTypeID, &send)
+
+	if send.FormID != 999 {
+		t.Fatalf("form id = %d, want 999", send.FormID)
+	}
+
+	if _, ok := send.Invoice.(*tg.InputInvoiceStarGift); !ok {
+		t.Fatalf("send invoice = %#v, want star gift", send.Invoice)
+	}
+}
+
+func TestSendGiftInvalidID(t *testing.T) {
+	inv := newMockInvoker()
+
+	err := newMockBot(inv).SendGift(context.Background(), userRef(42, 7), "not-a-number")
+	if err == nil {
+		t.Fatal("expected error for invalid gift id")
+	}
+
+	if inv.count() != 0 {
+		t.Fatalf("made %d RPC calls, want 0", inv.count())
+	}
+}