feat: add GetMyStarBalance

GetMyStarBalance (payments.getStarsStatus) returning the bot's Telegram
Stars balance as a StarAmount.

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

Author: ernado

star_balance.go

@@ -0,0 +1,34 @@
+package botapi
+
+import (
+	"context"
+
+	"github.com/gotd/td/tg"
+)
+
+// StarAmount describes an amount of Telegram Stars.
+type StarAmount struct {
+	// Amount is the integer number of Telegram Stars, rounded to 0; can be
+	// negative.
+	Amount int `json:"amount"`
+	// NanostarAmount is the number of 1/1000000000 shares of Telegram Stars,
+	// rounded to 0; can be negative.
+	NanostarAmount int `json:"nanostar_amount,omitempty"`
+}
+
+// GetMyStarBalance returns the current Telegram Stars balance of the bot.
+func (b *Bot) GetMyStarBalance(ctx context.Context) (StarAmount, error) {
+	res, err := b.raw.PaymentsGetStarsStatus(ctx, &tg.PaymentsGetStarsStatusRequest{
+		Peer: &tg.InputPeerSelf{},
+	})
+	if err != nil {
+		return StarAmount{}, asAPIError(err)
+	}
+
+	amount, ok := res.Balance.(*tg.StarsAmount)
+	if !ok {
+		return StarAmount{}, &Error{Code: 500, Description: "Internal Server Error: unexpected stars balance"}
+	}
+
+	return StarAmount{Amount: int(amount.Amount), NanostarAmount: amount.Nanos}, nil
+}

star_balance_test.go

@@ -0,0 +1,32 @@
+package botapi
+
+import (
+	"context"
+	"testing"
+
+	"github.com/gotd/td/tg"
+)
+
+func TestGetMyStarBalance(t *testing.T) {
+	inv := newMockInvoker()
+	inv.reply(tg.PaymentsGetStarsStatusRequestTypeID, &tg.PaymentsStarsStatus{
+		Balance: &tg.StarsAmount{Amount: 1500, Nanos: 250},
+	})
+
+	got, err := newMockBot(inv).GetMyStarBalance(context.Background())
+	if err != nil {
+		t.Fatalf("GetMyStarBalance: %v", err)
+	}
+
+	if got.Amount != 1500 || got.NanostarAmount != 250 {
+		t.Fatalf("balance = %#v", got)
+	}
+
+	var req tg.PaymentsGetStarsStatusRequest
+
+	inv.decode(t, tg.PaymentsGetStarsStatusRequestTypeID, &req)
+
+	if _, ok := req.Peer.(*tg.InputPeerSelf); !ok {
+		t.Fatalf("peer = %#v, want self", req.Peer)
+	}
+}