feat(members): implement chat member management

Add ban/unban/restrict/promote and GetChatMember(s)/GetChatAdministrators/
GetChatMemberCount over the MTProto channels.* API for supergroups and
channels. Introduce ChatPermissions and ChatAdminRights with mapping to
MTProto banned/admin rights, and a participant -> ChatMember converter.

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

Author: ernado

chat_member_methods.go

@@ -0,0 +1,241 @@
+package botapi
+
+import (
+	"context"
+
+	"github.com/gotd/td/telegram/peers"
+	"github.com/gotd/td/tg"
+)
+
+// resolveChannel resolves a ChatID to its MTProto input channel. Member
+// management is only available in supergroups and channels.
+func (b *Bot) resolveChannel(ctx context.Context, chat ChatID) (tg.InputChannelClass, error) {
+	p, err := b.resolvePeer(ctx, chat)
+	if err != nil {
+		return nil, err
+	}
+	ch, ok := p.(peers.Channel)
+	if !ok {
+		return nil, &Error{Code: 400, Description: "Bad Request: method is available only for supergroups and channels"}
+	}
+	return ch.InputChannel(), nil
+}
+
+// BanChatMemberOption configures a BanChatMember call.
+type BanChatMemberOption func(*banConfig)
+
+type banConfig struct {
+	untilDate     int
+	revokeHistory bool
+}
+
+// WithBanUntil sets the Unix time when the user will be unbanned (0 or far in
+// the future means forever).
+func WithBanUntil(untilDate int) BanChatMemberOption {
+	return func(c *banConfig) { c.untilDate = untilDate }
+}
+
+// WithRevokeMessages deletes all messages from the user being banned.
+func WithRevokeMessages() BanChatMemberOption {
+	return func(c *banConfig) { c.revokeHistory = true }
+}
+
+// BanChatMember bans a user from a supergroup or channel. The bot must be an
+// administrator with the can_restrict_members right.
+func (b *Bot) BanChatMember(ctx context.Context, chat ChatID, userID int64, opts ...BanChatMemberOption) error {
+	var cfg banConfig
+	for _, o := range opts {
+		o(&cfg)
+	}
+
+	channel, err := b.resolveChannel(ctx, chat)
+	if err != nil {
+		return err
+	}
+	user, err := b.resolveInputUser(ctx, userID)
+	if err != nil {
+		return err
+	}
+
+	if _, err := b.raw.ChannelsEditBanned(ctx, &tg.ChannelsEditBannedRequest{
+		Channel:     channel,
+		Participant: userToInputPeer(user),
+		BannedRights: tg.ChatBannedRights{
+			ViewMessages: true,
+			SendMessages: true,
+			SendMedia:    true,
+			SendStickers: true,
+			SendGifs:     true,
+			SendGames:    true,
+			SendInline:   true,
+			EmbedLinks:   true,
+			UntilDate:    cfg.untilDate,
+		},
+	}); err != nil {
+		return asAPIError(err)
+	}
+	if cfg.revokeHistory {
+		if _, err := b.raw.ChannelsDeleteParticipantHistory(ctx, &tg.ChannelsDeleteParticipantHistoryRequest{
+			Channel:     channel,
+			Participant: userToInputPeer(user),
+		}); err != nil {
+			return asAPIError(err)
+		}
+	}
+	return nil
+}
+
+// UnbanChatMember removes a user's ban from a supergroup or channel, clearing
+// all restrictions. It does not re-add the user to the chat.
+func (b *Bot) UnbanChatMember(ctx context.Context, chat ChatID, userID int64) error {
+	channel, err := b.resolveChannel(ctx, chat)
+	if err != nil {
+		return err
+	}
+	user, err := b.resolveInputUser(ctx, userID)
+	if err != nil {
+		return err
+	}
+
+	if _, err := b.raw.ChannelsEditBanned(ctx, &tg.ChannelsEditBannedRequest{
+		Channel:      channel,
+		Participant:  userToInputPeer(user),
+		BannedRights: tg.ChatBannedRights{}, // empty rights clear the ban
+	}); err != nil {
+		return asAPIError(err)
+	}
+	return nil
+}
+
+// RestrictChatMember restricts a user in a supergroup. permissions is an
+// allow-list; denied actions are turned into MTProto banned rights. untilDate is
+// a Unix time (0 means forever).
+func (b *Bot) RestrictChatMember(ctx context.Context, chat ChatID, userID int64, permissions ChatPermissions, untilDate int) error {
+	channel, err := b.resolveChannel(ctx, chat)
+	if err != nil {
+		return err
+	}
+	user, err := b.resolveInputUser(ctx, userID)
+	if err != nil {
+		return err
+	}
+
+	if _, err := b.raw.ChannelsEditBanned(ctx, &tg.ChannelsEditBannedRequest{
+		Channel:      channel,
+		Participant:  userToInputPeer(user),
+		BannedRights: permissions.toBannedRights(untilDate),
+	}); err != nil {
+		return asAPIError(err)
+	}
+	return nil
+}
+
+// PromoteChatMember promotes or demotes a user in a supergroup or channel. The
+// granted rights are the true fields of rights; pass a zero value to demote.
+func (b *Bot) PromoteChatMember(ctx context.Context, chat ChatID, userID int64, rights ChatAdminRights) error {
+	channel, err := b.resolveChannel(ctx, chat)
+	if err != nil {
+		return err
+	}
+	user, err := b.resolveInputUser(ctx, userID)
+	if err != nil {
+		return err
+	}
+
+	if _, err := b.raw.ChannelsEditAdmin(ctx, &tg.ChannelsEditAdminRequest{
+		Channel:     channel,
+		UserID:      user,
+		AdminRights: rights.toTg(),
+		Rank:        rights.CustomTitle,
+	}); err != nil {
+		return asAPIError(err)
+	}
+	return nil
+}
+
+// GetChatMember returns information about a member of a supergroup or channel.
+func (b *Bot) GetChatMember(ctx context.Context, chat ChatID, userID int64) (ChatMember, error) {
+	channel, err := b.resolveChannel(ctx, chat)
+	if err != nil {
+		return nil, err
+	}
+	user, err := b.resolveInputUser(ctx, userID)
+	if err != nil {
+		return nil, err
+	}
+
+	res, err := b.raw.ChannelsGetParticipant(ctx, &tg.ChannelsGetParticipantRequest{
+		Channel:     channel,
+		Participant: userToInputPeer(user),
+	})
+	if err != nil {
+		return nil, asAPIError(err)
+	}
+	return chatMemberFromParticipant(res.Participant, usersByID(res.Users)), nil
+}
+
+// GetChatAdministrators returns the administrators of a supergroup or channel,
+// excluding other bots.
+func (b *Bot) GetChatAdministrators(ctx context.Context, chat ChatID) ([]ChatMember, error) {
+	channel, err := b.resolveChannel(ctx, chat)
+	if err != nil {
+		return nil, err
+	}
+
+	res, err := b.raw.ChannelsGetParticipants(ctx, &tg.ChannelsGetParticipantsRequest{
+		Channel: channel,
+		Filter:  &tg.ChannelParticipantsAdmins{},
+		Limit:   200,
+	})
+	if err != nil {
+		return nil, asAPIError(err)
+	}
+	participants, ok := res.AsModified()
+	if !ok {
+		return nil, &Error{Code: 500, Description: "Internal Server Error: unexpected participants response"}
+	}
+
+	users := usersByID(participants.Users)
+	out := make([]ChatMember, 0, len(participants.Participants))
+	for _, p := range participants.Participants {
+		out = append(out, chatMemberFromParticipant(p, users))
+	}
+	return out, nil
+}
+
+// GetChatMemberCount returns the number of members in a supergroup or channel.
+func (b *Bot) GetChatMemberCount(ctx context.Context, chat ChatID) (int, error) {
+	channel, err := b.resolveChannel(ctx, chat)
+	if err != nil {
+		return 0, err
+	}
+
+	res, err := b.raw.ChannelsGetParticipants(ctx, &tg.ChannelsGetParticipantsRequest{
+		Channel: channel,
+		Filter:  &tg.ChannelParticipantsRecent{},
+		Limit:   1,
+	})
+	if err != nil {
+		return 0, asAPIError(err)
+	}
+	participants, ok := res.AsModified()
+	if !ok {
+		return 0, &Error{Code: 500, Description: "Internal Server Error: unexpected participants response"}
+	}
+	return participants.Count, nil
+}
+
+// userToInputPeer wraps an input user as the input peer the participant-editing
+// methods expect.
+func userToInputPeer(u tg.InputUserClass) tg.InputPeerClass {
+	switch v := u.(type) {
+	case *tg.InputUser:
+		return &tg.InputPeerUser{UserID: v.UserID, AccessHash: v.AccessHash}
+	case *tg.InputUserFromMessage:
+		return &tg.InputPeerUserFromMessage{Peer: v.Peer, MsgID: v.MsgID, UserID: v.UserID}
+	case *tg.InputUserSelf:
+		return &tg.InputPeerSelf{}
+	default:
+		return &tg.InputPeerEmpty{}
+	}
+}

chat_permissions.go

@@ -0,0 +1,87 @@
+package botapi
+
+import "github.com/gotd/td/tg"
+
+// ChatPermissions describes the actions a non-administrator user is allowed to
+// take in a chat. A nil/false field denies the action.
+type ChatPermissions struct {
+	CanSendMessages       bool `json:"can_send_messages,omitempty"`
+	CanSendAudios         bool `json:"can_send_audios,omitempty"`
+	CanSendDocuments      bool `json:"can_send_documents,omitempty"`
+	CanSendPhotos         bool `json:"can_send_photos,omitempty"`
+	CanSendVideos         bool `json:"can_send_videos,omitempty"`
+	CanSendVideoNotes     bool `json:"can_send_video_notes,omitempty"`
+	CanSendVoiceNotes     bool `json:"can_send_voice_notes,omitempty"`
+	CanSendPolls          bool `json:"can_send_polls,omitempty"`
+	CanSendOtherMessages  bool `json:"can_send_other_messages,omitempty"`
+	CanAddWebPagePreviews bool `json:"can_add_web_page_previews,omitempty"`
+	CanChangeInfo         bool `json:"can_change_info,omitempty"`
+	CanInviteUsers        bool `json:"can_invite_users,omitempty"`
+	CanPinMessages        bool `json:"can_pin_messages,omitempty"`
+	CanManageTopics       bool `json:"can_manage_topics,omitempty"`
+}
+
+// ChatAdminRights describes the administrator privileges granted to a user in a
+// supergroup or channel. It mirrors the Bot API promoteChatMember parameters.
+type ChatAdminRights struct {
+	IsAnonymous         bool `json:"is_anonymous,omitempty"`
+	CanManageChat       bool `json:"can_manage_chat,omitempty"`
+	CanDeleteMessages   bool `json:"can_delete_messages,omitempty"`
+	CanManageVideoChats bool `json:"can_manage_video_chats,omitempty"`
+	CanRestrictMembers  bool `json:"can_restrict_members,omitempty"`
+	CanPromoteMembers   bool `json:"can_promote_members,omitempty"`
+	CanChangeInfo       bool `json:"can_change_info,omitempty"`
+	CanInviteUsers      bool `json:"can_invite_users,omitempty"`
+	CanPostMessages     bool `json:"can_post_messages,omitempty"`
+	CanEditMessages     bool `json:"can_edit_messages,omitempty"`
+	CanPinMessages      bool `json:"can_pin_messages,omitempty"`
+	CanManageTopics     bool `json:"can_manage_topics,omitempty"`
+	// CustomTitle is the administrator's rank (custom title), if any.
+	CustomTitle string `json:"custom_title,omitempty"`
+}
+
+// toTg converts the Bot API admin rights to the MTProto representation.
+func (r ChatAdminRights) toTg() tg.ChatAdminRights {
+	return tg.ChatAdminRights{
+		ChangeInfo:     r.CanChangeInfo,
+		PostMessages:   r.CanPostMessages,
+		EditMessages:   r.CanEditMessages,
+		DeleteMessages: r.CanDeleteMessages,
+		BanUsers:       r.CanRestrictMembers,
+		InviteUsers:    r.CanInviteUsers,
+		PinMessages:    r.CanPinMessages,
+		AddAdmins:      r.CanPromoteMembers,
+		Anonymous:      r.IsAnonymous,
+		ManageCall:     r.CanManageVideoChats,
+		Other:          r.CanManageChat,
+		ManageTopics:   r.CanManageTopics,
+	}
+}
+
+// toBannedRights turns the allow-list permissions into MTProto banned rights,
+// where a set bit denies the action. untilDate is a Unix time (0 = forever).
+func (p ChatPermissions) toBannedRights(untilDate int) tg.ChatBannedRights {
+	canSendAnyMedia := p.CanSendAudios || p.CanSendDocuments || p.CanSendPhotos ||
+		p.CanSendVideos || p.CanSendVideoNotes || p.CanSendVoiceNotes
+	return tg.ChatBannedRights{
+		SendMessages:    !p.CanSendMessages,
+		SendMedia:       !canSendAnyMedia,
+		SendAudios:      !p.CanSendAudios,
+		SendDocs:        !p.CanSendDocuments,
+		SendPhotos:      !p.CanSendPhotos,
+		SendVideos:      !p.CanSendVideos,
+		SendRoundvideos: !p.CanSendVideoNotes,
+		SendVoices:      !p.CanSendVoiceNotes,
+		SendPolls:       !p.CanSendPolls,
+		SendStickers:    !p.CanSendOtherMessages,
+		SendGifs:        !p.CanSendOtherMessages,
+		SendGames:       !p.CanSendOtherMessages,
+		SendInline:      !p.CanSendOtherMessages,
+		EmbedLinks:      !p.CanAddWebPagePreviews,
+		ChangeInfo:      !p.CanChangeInfo,
+		InviteUsers:     !p.CanInviteUsers,
+		PinMessages:     !p.CanPinMessages,
+		ManageTopics:    !p.CanManageTopics,
+		UntilDate:       untilDate,
+	}
+}