client

package
v0.1.4 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: May 11, 2026 License: MIT Imports: 18 Imported by: 0

Documentation

Overview

Package client defines the narrow Telegram interface used by all command runners. Production wires this to gotd/td; tests use FakeClient.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func DisplayName

func DisplayName(firstName, lastName, username string, id int64) string

DisplayName mirrors Python _display_title.

func EnsureCredentials

func EnsureCredentials() (apiID int, apiHash string, err error)

EnsureCredentials reads TG_API_ID and TG_API_HASH and returns them, or a *safety.MissingCredentials error pointing the user at https://my.telegram.org/apps. Mirrors tgcli.client.ensure_credentials.

func FlowFromPrompt

func FlowFromPrompt(p AuthPrompt) auth.Flow

FlowFromPrompt converts AuthPrompt into a gotd auth.Flow.

Types

type AdminActionReq

type AdminActionReq struct {
	Action string
	ChatID int64
	UserID int64
	Value  string
	Path   string
	Flags  map[string]bool
}

type AuthPrompt

type AuthPrompt struct {
	Phone     func() (string, error)
	Code      func(ctx context.Context, sentCode *tg.AuthSentCode) (string, error)
	Password  func(ctx context.Context) (string, error)
	AcceptTOS func(ctx context.Context, terms tg.HelpTermsOfService) error
}

AuthPrompt is the interactive callback set used during `tg login`. Each callback is allowed to read from stdin / write to stderr.

type BackfillMessage

type BackfillMessage struct {
	ChatID       int64
	MessageID    int64
	SenderID     int64
	Date         string
	Text         string
	IsOutgoing   bool
	ReplyToMsgID int64
	HasMedia     bool
	MediaType    string
	MediaPath    string
	RawJSON      string
}

type BackfillReq

type BackfillReq struct {
	ChatID int64
	Limit  int
}

type BlockUserReq

type BlockUserReq struct {
	UserID int64
}

BlockUserReq / UnblockUserReq mirror contacts.Block/Unblock.

type ChatInfo

type ChatInfo struct {
	ID       int64  `json:"chat_id"`
	Type     string `json:"type"`
	Title    string `json:"title"`
	Username string `json:"username"`
}

type Client

type Client interface {
	GetMe(ctx context.Context) (User, error)
	SendMessage(ctx context.Context, req SendMessageReq) (SendMessageResp, error)
	UploadFile(ctx context.Context, req UploadFileReq) (UploadFileResp, error)
	EditMessage(ctx context.Context, req EditMessageReq) error
	Forward(ctx context.Context, req ForwardReq) (ForwardResp, error)
	Pin(ctx context.Context, req PinReq) error
	React(ctx context.Context, req ReactReq) error
	MarkRead(ctx context.Context, req MarkReadReq) error
	DeleteMessages(ctx context.Context, req DeleteMessagesReq) (DeleteMessagesResp, error)
	LeaveChat(ctx context.Context, req LeaveChatReq) error
	BlockUser(ctx context.Context, req BlockUserReq) error
	UnblockUser(ctx context.Context, req BlockUserReq) error
	ListSessions(ctx context.Context) ([]SessionRef, error)
	TerminateSession(ctx context.Context, req TerminateSessionReq) error
	DiscoverDialogs(ctx context.Context, limit int) ([]ChatInfo, error)
	SyncContacts(ctx context.Context) ([]ContactInfo, error)
	BackfillMessages(ctx context.Context, req BackfillReq) ([]BackfillMessage, error)
	ListTopics(ctx context.Context, chatID int64, limit int, query string) ([]TopicInfo, error)
	CreateTopic(ctx context.Context, req CreateTopicReq) (CreateTopicResp, error)
	EditTopic(ctx context.Context, req EditTopicReq) error
	PinTopic(ctx context.Context, req PinTopicReq) error
	ListFolders(ctx context.Context) ([]FolderInfo, error)
	UpdateFolder(ctx context.Context, req FolderUpdateReq) error
	DeleteFolder(ctx context.Context, id int64) error
	ReorderFolders(ctx context.Context, ids []int64) error
	ListPinnedDialogs(ctx context.Context, chatID int64) ([]ChatInfo, error)
	AdminAction(ctx context.Context, req AdminActionReq) (InviteLinkResp, error)
	ListChatMembers(ctx context.Context, chatID int64, limit int) ([]MemberInfo, error)
	GetChatsInfo(ctx context.Context, ids []int64) ([]ChatInfo, error)
	ListenOnce(ctx context.Context) (ListenEvent, error)
	Close() error
}

Client is the narrow API command runners use.

type ContactInfo

type ContactInfo struct {
	UserID    int64
	Phone     string
	FirstName string
	LastName  string
	Username  string
	IsMutual  bool
}

type CreateTopicReq

type CreateTopicReq struct {
	ChatID      int64
	Title       string
	IconColor   int
	IconEmojiID int64
}

type CreateTopicResp

type CreateTopicResp struct {
	TopicID int64
	Title   string
}

type DeleteMessagesReq

type DeleteMessagesReq struct {
	ChatID      int64
	MessageIDs  []int64
	ForEveryone bool
}

DeleteMessagesReq mirrors messages.DeleteMessages.

type DeleteMessagesResp

type DeleteMessagesResp struct {
	Deleted int
}

type EditMessageReq

type EditMessageReq struct {
	ChatID    int64
	MessageID int64
	NewText   string
}

EditMessageReq mirrors messages.EditMessage.

type EditTopicReq

type EditTopicReq struct {
	ChatID      int64
	TopicID     int64
	Title       string
	IconEmojiID int64
}

type FakeClient

type FakeClient struct {
	Me       User
	NextErr  error
	Closed   bool
	Calls    []string
	Sent     []SendMessageReq
	Uploads  []UploadFileReq
	Edited   []EditMessageReq
	Forwards []ForwardReq
	Pins     []PinReq
	Reacts   []ReactReq
	Reads    []MarkReadReq
	Deletes  []DeleteMessagesReq
	Leaves   []LeaveChatReq
	Blocks   []BlockUserReq
	Unblocks []BlockUserReq
	Sessions []SessionRef
	Terms    []TerminateSessionReq
	Dialogs  []ChatInfo
	Contacts []ContactInfo

	Discoveries  []int
	ContactSyncs []bool
	Backfills    []BackfillReq
	BackfillRows []BackfillMessage
	Topics       []TopicInfo
	NextTopicID  int64
	Folders      []FolderInfo

	TopicCreates   []CreateTopicReq
	TopicEdits     []EditTopicReq
	TopicPins      []PinTopicReq
	FolderUpdates  []FolderUpdateReq
	FolderDeletes  []int64
	FolderReorders [][]int64
	PinnedLists    []int64
	AdminActions   []AdminActionReq
	Members        []MemberInfo
	ChatInfos      []ChatInfo
	ListenEvents   []ListenEvent
	ListenCalls    []bool

	// LastMessageID is the next id returned by SendMessage. Tests override this.
	NextMessageID int64
}

FakeClient is the test double for the Client interface. It records every call and lets tests assert on the captured arguments.

func (*FakeClient) AdminAction

func (f *FakeClient) AdminAction(_ context.Context, req AdminActionReq) (InviteLinkResp, error)

func (*FakeClient) BackfillMessages

func (f *FakeClient) BackfillMessages(_ context.Context, req BackfillReq) ([]BackfillMessage, error)

func (*FakeClient) BlockUser

func (f *FakeClient) BlockUser(_ context.Context, req BlockUserReq) error

func (*FakeClient) Close

func (f *FakeClient) Close() error

func (*FakeClient) CreateTopic

func (f *FakeClient) CreateTopic(_ context.Context, req CreateTopicReq) (CreateTopicResp, error)

func (*FakeClient) DeleteFolder

func (f *FakeClient) DeleteFolder(_ context.Context, id int64) error

func (*FakeClient) DeleteMessages

func (f *FakeClient) DeleteMessages(_ context.Context, req DeleteMessagesReq) (DeleteMessagesResp, error)

func (*FakeClient) DiscoverDialogs

func (f *FakeClient) DiscoverDialogs(_ context.Context, limit int) ([]ChatInfo, error)

func (*FakeClient) EditMessage

func (f *FakeClient) EditMessage(_ context.Context, req EditMessageReq) error

func (*FakeClient) EditTopic

func (f *FakeClient) EditTopic(_ context.Context, req EditTopicReq) error

func (*FakeClient) Forward

func (f *FakeClient) Forward(_ context.Context, req ForwardReq) (ForwardResp, error)

func (*FakeClient) GetChatsInfo

func (f *FakeClient) GetChatsInfo(_ context.Context, ids []int64) ([]ChatInfo, error)

func (*FakeClient) GetMe

func (f *FakeClient) GetMe(_ context.Context) (User, error)

func (*FakeClient) LeaveChat

func (f *FakeClient) LeaveChat(_ context.Context, req LeaveChatReq) error

func (*FakeClient) ListChatMembers

func (f *FakeClient) ListChatMembers(_ context.Context, chatID int64, limit int) ([]MemberInfo, error)

func (*FakeClient) ListFolders

func (f *FakeClient) ListFolders(_ context.Context) ([]FolderInfo, error)

func (*FakeClient) ListPinnedDialogs

func (f *FakeClient) ListPinnedDialogs(_ context.Context, chatID int64) ([]ChatInfo, error)

func (*FakeClient) ListSessions

func (f *FakeClient) ListSessions(_ context.Context) ([]SessionRef, error)

func (*FakeClient) ListTopics

func (f *FakeClient) ListTopics(_ context.Context, chatID int64, limit int, query string) ([]TopicInfo, error)

func (*FakeClient) ListenOnce

func (f *FakeClient) ListenOnce(_ context.Context) (ListenEvent, error)

func (*FakeClient) MarkRead

func (f *FakeClient) MarkRead(_ context.Context, req MarkReadReq) error

func (*FakeClient) Pin

func (f *FakeClient) Pin(_ context.Context, req PinReq) error

func (*FakeClient) PinTopic

func (f *FakeClient) PinTopic(_ context.Context, req PinTopicReq) error

func (*FakeClient) React

func (f *FakeClient) React(_ context.Context, req ReactReq) error

func (*FakeClient) ReorderFolders

func (f *FakeClient) ReorderFolders(_ context.Context, ids []int64) error

func (*FakeClient) SendMessage

func (f *FakeClient) SendMessage(_ context.Context, req SendMessageReq) (SendMessageResp, error)

func (*FakeClient) SyncContacts

func (f *FakeClient) SyncContacts(_ context.Context) ([]ContactInfo, error)

func (*FakeClient) TerminateSession

func (f *FakeClient) TerminateSession(_ context.Context, req TerminateSessionReq) error

func (*FakeClient) UnblockUser

func (f *FakeClient) UnblockUser(_ context.Context, req BlockUserReq) error

func (*FakeClient) UpdateFolder

func (f *FakeClient) UpdateFolder(_ context.Context, req FolderUpdateReq) error

func (*FakeClient) UploadFile

func (f *FakeClient) UploadFile(_ context.Context, req UploadFileReq) (UploadFileResp, error)

type FolderInfo

type FolderInfo struct {
	ID             int64
	Title          string
	Emoji          string
	IncludeChatIDs []int64
	ExcludeChatIDs []int64
	IsDefault      bool
}

type FolderUpdateReq

type FolderUpdateReq struct {
	ID             int64
	Title          string
	Emoji          string
	IncludeChatIDs []int64
	ExcludeChatIDs []int64
}

type ForwardReq

type ForwardReq struct {
	FromChatID int64
	MessageIDs []int64
	ToChatID   int64
	TopicID    int64
}

ForwardReq mirrors messages.ForwardMessages.

type ForwardResp

type ForwardResp struct {
	MessageIDs []int64
}

type GotdClient

type GotdClient struct {
	// contains filtered or unexported fields
}

GotdClient is the production Client implementation backed by gotd/td.

gotd/td's telegram.Client.Run is blocking and owns the connection lifecycle, so we run it in a background goroutine and proxy API calls in. Close() cancels Run and waits for the goroutine to exit, ensuring the session file flushes cleanly.

func New

func New(ctx context.Context, apiID int, apiHash, sessionPath, dbPath string) (*GotdClient, error)

New opens a gotd client against an existing session, starts Run in a goroutine, and returns a Client that proxies API calls into it. The returned Client must be closed to release the connection.

func (*GotdClient) AdminAction

func (g *GotdClient) AdminAction(ctx context.Context, req AdminActionReq) (InviteLinkResp, error)

func (*GotdClient) BackfillMessages

func (g *GotdClient) BackfillMessages(ctx context.Context, req BackfillReq) ([]BackfillMessage, error)

func (*GotdClient) BlockUser

func (g *GotdClient) BlockUser(ctx context.Context, req BlockUserReq) error

func (*GotdClient) Close

func (g *GotdClient) Close() error

Close cancels the underlying client.Run and waits for it to drain.

func (*GotdClient) CreateTopic

func (g *GotdClient) CreateTopic(ctx context.Context, req CreateTopicReq) (CreateTopicResp, error)

func (*GotdClient) DeleteFolder

func (g *GotdClient) DeleteFolder(ctx context.Context, id int64) error

func (*GotdClient) DeleteMessages

func (g *GotdClient) DeleteMessages(ctx context.Context, req DeleteMessagesReq) (DeleteMessagesResp, error)

func (*GotdClient) DiscoverDialogs

func (g *GotdClient) DiscoverDialogs(ctx context.Context, limit int) ([]ChatInfo, error)

func (*GotdClient) EditMessage

func (g *GotdClient) EditMessage(ctx context.Context, req EditMessageReq) error

func (*GotdClient) EditTopic

func (g *GotdClient) EditTopic(ctx context.Context, req EditTopicReq) error

func (*GotdClient) Forward

func (g *GotdClient) Forward(ctx context.Context, req ForwardReq) (ForwardResp, error)

func (*GotdClient) GetChatsInfo

func (g *GotdClient) GetChatsInfo(ctx context.Context, ids []int64) ([]ChatInfo, error)

func (*GotdClient) GetMe

func (g *GotdClient) GetMe(ctx context.Context) (User, error)

func (*GotdClient) LeaveChat

func (g *GotdClient) LeaveChat(ctx context.Context, req LeaveChatReq) error

func (*GotdClient) ListChatMembers

func (g *GotdClient) ListChatMembers(ctx context.Context, chatID int64, limit int) ([]MemberInfo, error)

func (*GotdClient) ListFolders

func (g *GotdClient) ListFolders(ctx context.Context) ([]FolderInfo, error)

func (*GotdClient) ListPinnedDialogs

func (g *GotdClient) ListPinnedDialogs(ctx context.Context, chatID int64) ([]ChatInfo, error)

func (*GotdClient) ListSessions

func (g *GotdClient) ListSessions(ctx context.Context) ([]SessionRef, error)

func (*GotdClient) ListTopics

func (g *GotdClient) ListTopics(ctx context.Context, chatID int64, limit int, query string) ([]TopicInfo, error)

func (*GotdClient) ListenOnce

func (g *GotdClient) ListenOnce(ctx context.Context) (ListenEvent, error)

func (*GotdClient) MarkRead

func (g *GotdClient) MarkRead(ctx context.Context, req MarkReadReq) error

func (*GotdClient) Pin

func (g *GotdClient) Pin(ctx context.Context, req PinReq) error

func (*GotdClient) PinTopic

func (g *GotdClient) PinTopic(ctx context.Context, req PinTopicReq) error

func (*GotdClient) React

func (g *GotdClient) React(ctx context.Context, req ReactReq) error

func (*GotdClient) ReorderFolders

func (g *GotdClient) ReorderFolders(ctx context.Context, ids []int64) error

func (*GotdClient) SendMessage

func (g *GotdClient) SendMessage(ctx context.Context, req SendMessageReq) (SendMessageResp, error)

func (*GotdClient) SendMessageBySelector

func (g *GotdClient) SendMessageBySelector(ctx context.Context, selector, text string, replyTo int64, silent, noWeb bool) (SendMessageResp, error)

SendMessageBySelector resolves selector via Telegram and sends in one call. Bypasses the cached-access-hash requirement so users can send today.

func (*GotdClient) SyncContacts

func (g *GotdClient) SyncContacts(ctx context.Context) ([]ContactInfo, error)

func (*GotdClient) TerminateSession

func (g *GotdClient) TerminateSession(ctx context.Context, req TerminateSessionReq) error

func (*GotdClient) UnblockUser

func (g *GotdClient) UnblockUser(ctx context.Context, req BlockUserReq) error

func (*GotdClient) UpdateFolder

func (g *GotdClient) UpdateFolder(ctx context.Context, req FolderUpdateReq) error

func (*GotdClient) UploadFile

func (g *GotdClient) UploadFile(ctx context.Context, req UploadFileReq) (UploadFileResp, error)

type InviteLinkResp

type InviteLinkResp struct {
	Link string
}

type LeaveChatReq

type LeaveChatReq struct {
	ChatID int64
}

LeaveChatReq mirrors channels.LeaveChannel / messages.DeleteChatUser.

type ListenEvent

type ListenEvent struct {
	UpdateKind string `json:"update_kind"`
	ChatID     int64  `json:"chat_id"`
	MessageID  int64  `json:"message_id"`
	SenderID   int64  `json:"sender_id,omitempty"`
	Text       string `json:"text,omitempty"`
	MediaType  string `json:"media_type,omitempty"`
}

type LoginOptions

type LoginOptions struct {
	APIID   int
	APIHash string
	Session string
	Prompt  AuthPrompt
}

LoginOptions configures the login flow.

type MarkReadReq

type MarkReadReq struct {
	ChatID int64
	UpToID int64
}

MarkReadReq mirrors messages.ReadHistory.

type MemberInfo

type MemberInfo struct {
	UserID      int64  `json:"user_id"`
	Username    string `json:"username"`
	DisplayName string `json:"display_name"`
	Role        string `json:"role"`
}

type PinReq

type PinReq struct {
	ChatID    int64
	MessageID int64
	Silent    bool
	Unpin     bool // true = unpin
}

PinReq mirrors messages.UpdatePinnedMessage / Unpin.

type PinTopicReq

type PinTopicReq struct {
	ChatID  int64
	TopicID int64
	Pinned  bool
}

type ReactReq

type ReactReq struct {
	ChatID    int64
	MessageID int64
	Emoji     string // empty = remove reaction
	Big       bool
}

ReactReq mirrors messages.SendReaction.

type SendMessageReq

type SendMessageReq struct {
	ChatID    int64
	Text      string
	ReplyTo   int64 // 0 = no reply
	TopicID   int64 // 0 = no topic / general
	Silent    bool
	NoWebpage bool
}

SendMessageReq mirrors the input to messages.SendMessage.

type SendMessageResp

type SendMessageResp struct {
	MessageID int64
	Date      string
}

type SessionRef

type SessionRef struct {
	Hash       int64  `json:"hash"`
	DeviceName string `json:"device_name"`
	Platform   string `json:"platform"`
	IsCurrent  bool   `json:"is_current"`
}

SessionRef is one row from account.GetAuthorizations.

type TerminateSessionReq

type TerminateSessionReq struct {
	Hash int64
}

TerminateSessionReq mirrors account.ResetAuthorization.

type TopicInfo

type TopicInfo struct {
	ID           int64
	Title        string
	IconEmojiID  int64
	Closed       bool
	Hidden       bool
	TopMessageID int64
	UnreadCount  int
}

type UploadFileReq

type UploadFileReq struct {
	ChatID            int64
	Path              string
	Kind              string
	Caption           string
	ReplyTo           int64
	Silent            bool
	Filename          string
	SupportsStreaming bool
}

UploadFileReq mirrors messages.SendMedia with an uploaded file.

type UploadFileResp

type UploadFileResp struct {
	MessageID int64
	Date      string
}

type User

type User struct {
	ID          int64
	Username    string
	Phone       string
	FirstName   string
	LastName    string
	IsBot       bool
	DisplayName string
	RawJSON     string
}

User mirrors the subset of fields tgcli.commands.auth uses.

func Login

func Login(ctx context.Context, opts LoginOptions) (User, error)

Login runs an interactive auth flow that persists a session at LoginOptions.Session. It blocks until the user is authorized.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL