feat: add GiftPremiumSubscription

Gifts a Telegram Premium subscription to a user via the Telegram Stars payment
flow with inputInvoicePremiumGiftStars. The Stars cost is determined by the
payment form for the chosen month count, so it is not a parameter.

Generalizes payStarsForm to accept any star payment form (starsFormID handles
both paymentFormStarGift and paymentFormStars), reusing the same two-step flow
introduced for SendGift. Text is resolved through the shared giftMessage helper.

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

Author: ernado

send_gift.go

@@ -78,6 +78,39 @@ func (b *Bot) SendGift(ctx context.Context, target ChatID, giftID string, opts .
 	return b.payStarsForm(ctx, invoice)
 }
 
+// GiftPremiumSubscription gifts a Telegram Premium subscription to a user for
+// the given number of months. The Telegram Stars cost is determined by the
+// payment form for the chosen duration. WithGiftPayForUpgrade has no effect
+// here.
+func (b *Bot) GiftPremiumSubscription(ctx context.Context, userID int64, months int, opts ...GiftOption) error {
+	var cfg giftConfig
+
+	for _, opt := range opts {
+		opt(&cfg)
+	}
+
+	user, err := b.resolveInputUser(ctx, userID)
+	if err != nil {
+		return err
+	}
+
+	invoice := &tg.InputInvoicePremiumGiftStars{
+		UserID: user,
+		Months: months,
+	}
+
+	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) {
@@ -98,17 +131,31 @@ func (b *Bot) payStarsForm(ctx context.Context, invoice tg.InputInvoiceClass) er
 		return asAPIError(err)
 	}
 
-	stars, ok := form.(*tg.PaymentsPaymentFormStarGift)
-	if !ok {
-		return &Error{Code: 500, Description: "Internal Server Error: unexpected payment form"}
+	formID, err := starsFormID(form)
+	if err != nil {
+		return err
 	}
 
 	if _, err := b.raw.PaymentsSendStarsForm(ctx, &tg.PaymentsSendStarsFormRequest{
-		FormID:  stars.FormID,
+		FormID:  formID,
 		Invoice: invoice,
 	}); err != nil {
 		return asAPIError(err)
 	}
 
 	return nil
 }
+
+// starsFormID extracts the form id from a Telegram Stars payment form. Star
+// gifts return a starGift form; subscriptions and other star purchases return a
+// plain stars form.
+func starsFormID(form tg.PaymentsPaymentFormClass) (int64, error) {
+	switch f := form.(type) {
+	case *tg.PaymentsPaymentFormStarGift:
+		return f.FormID, nil
+	case *tg.PaymentsPaymentFormStars:
+		return f.FormID, nil
+	default:
+		return 0, &Error{Code: 500, Description: "Internal Server Error: unexpected payment form"}
+	}
+}

send_gift_test.go

@@ -63,6 +63,53 @@ func TestSendGift(t *testing.T) {
 	}
 }
 
+func TestGiftPremiumSubscription(t *testing.T) {
+	inv := newMockInvoker()
+	inv.reply(tg.PaymentsGetPaymentFormRequestTypeID, &tg.PaymentsPaymentFormStars{
+		FormID:  555,
+		Invoice: tg.Invoice{Currency: "XTR"},
+	})
+	inv.reply(tg.PaymentsSendStarsFormRequestTypeID, &tg.PaymentsPaymentResult{
+		Updates: &tg.Updates{},
+	})
+
+	bot := newMockBot(inv)
+
+	err := bot.GiftPremiumSubscription(context.Background(), 42, 6, WithGiftText("enjoy"))
+	if err != nil {
+		t.Fatalf("GiftPremiumSubscription: %v", err)
+	}
+
+	var form tg.PaymentsGetPaymentFormRequest
+
+	inv.decode(t, tg.PaymentsGetPaymentFormRequestTypeID, &form)
+
+	invoice, ok := form.Invoice.(*tg.InputInvoicePremiumGiftStars)
+	if !ok {
+		t.Fatalf("invoice = %#v, want premium gift stars", form.Invoice)
+	}
+
+	if invoice.Months != 6 {
+		t.Fatalf("months = %d, want 6", invoice.Months)
+	}
+
+	if invoice.Message.Text != "enjoy" {
+		t.Fatalf("message = %q", invoice.Message.Text)
+	}
+
+	if _, ok := invoice.UserID.(*tg.InputUser); !ok {
+		t.Fatalf("user = %#v, want input user", invoice.UserID)
+	}
+
+	var send tg.PaymentsSendStarsFormRequest
+
+	inv.decode(t, tg.PaymentsSendStarsFormRequestTypeID, &send)
+
+	if send.FormID != 555 {
+		t.Fatalf("form id = %d, want 555", send.FormID)
+	}
+}
+
 func TestSendGiftInvalidID(t *testing.T) {
 	inv := newMockInvoker()