beeperapi

package
v0.17.0 Latest Latest
Warning

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

Go to latest
Published: Mar 5, 2026 License: MIT Imports: 17 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func FormatError

func FormatError(err error) string

FormatError converts SDK errors to user-friendly messages.

func IsAPIError

func IsAPIError(err error) bool

IsAPIError returns true if the error is an API error from the SDK.

func IsEventsUnauthorized added in v0.16.0

func IsEventsUnauthorized(err error) bool

IsEventsUnauthorized returns true when websocket auth fails.

func IsEventsUnsupported added in v0.16.0

func IsEventsUnsupported(err error) bool

IsEventsUnsupported returns true when /v1/ws is not available on this API build.

func IsNotFound

func IsNotFound(err error) bool

IsNotFound returns true if the error is a 404.

func IsUnauthorized

func IsUnauthorized(err error) bool

IsUnauthorized returns true if the error is a 401.

func IsUnsupportedRoute added in v0.10.0

func IsUnsupportedRoute(err error, method, pathContains string) bool

IsUnsupportedRoute returns true when an API route appears unavailable on the current Beeper Desktop API version.

Types

type Account

type Account struct {
	ID          string `json:"id"`
	DisplayName string `json:"display_name"`
	Network     string `json:"network"`
}

Account represents a messaging account (simplified view).

type AccountsService

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

AccountsService handles account operations.

func (*AccountsService) List

func (s *AccountsService) List(ctx context.Context) ([]Account, error)

List retrieves all accounts.

func (*AccountsService) ListContacts added in v0.15.0

func (s *AccountsService) ListContacts(ctx context.Context, accountID string, params ContactListParams) (ContactListResult, error)

ListContacts lists contacts on a specific account with cursor pagination.

func (*AccountsService) ListRaw

ListRaw retrieves accounts and returns the raw SDK response.

func (*AccountsService) SearchContacts added in v0.3.0

func (s *AccountsService) SearchContacts(ctx context.Context, accountID string, query string) ([]Contact, error)

SearchContacts finds contacts on a specific account.

type AssetServeResult added in v0.12.0

type AssetServeResult struct {
	ContentType   string `json:"content_type,omitempty"`
	ContentLength int64  `json:"content_length,omitempty"`
	BytesWritten  int64  `json:"bytes_written"`
}

AssetServeResult represents streamed response metadata.

type AssetUploadBase64Params added in v0.10.0

type AssetUploadBase64Params struct {
	Content  string
	FileName string
	MimeType string
}

AssetUploadBase64Params configures base64 upload requests.

type AssetUploadParams added in v0.10.0

type AssetUploadParams struct {
	FilePath string
	FileName string
	MimeType string
}

AssetUploadParams configures multipart upload requests.

type AssetUploadResult added in v0.10.0

type AssetUploadResult struct {
	UploadID string  `json:"upload_id"`
	SrcURL   string  `json:"src_url,omitempty"`
	FileName string  `json:"file_name,omitempty"`
	MimeType string  `json:"mime_type,omitempty"`
	FileSize int64   `json:"file_size,omitempty"`
	Duration float64 `json:"duration,omitempty"`
	Width    int     `json:"width,omitempty"`
	Height   int     `json:"height,omitempty"`
}

AssetUploadResult represents upload metadata.

type AssetsService added in v0.4.0

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

AssetsService handles asset operations.

func (*AssetsService) Download added in v0.4.0

func (s *AssetsService) Download(ctx context.Context, url string) (string, error)

Download retrieves a local file URL for an asset.

func (*AssetsService) Serve added in v0.12.0

func (s *AssetsService) Serve(ctx context.Context, url string, dst io.Writer) (AssetServeResult, error)

Serve streams an asset response to the provided writer.

func (*AssetsService) Upload added in v0.10.0

Upload stores a local file in temporary upload storage and returns an upload ID.

func (*AssetsService) UploadBase64 added in v0.10.0

UploadBase64 uploads a file payload encoded as base64.

type ChatCreateParams added in v0.3.0

type ChatCreateParams struct {
	AccountID      string
	ParticipantIDs []string
	Type           string // single|group
	Title          string
	MessageText    string
}

ChatCreateParams configures chat creation.

type ChatCreateResult added in v0.3.0

type ChatCreateResult struct {
	ChatID string `json:"chat_id"`
	Status string `json:"status,omitempty"`
}

ChatCreateResult is the response from creating a chat.

type ChatDetail

type ChatDetail struct {
	ID                     string `json:"id"`
	Title                  string `json:"title"`
	DisplayName            string `json:"display_name,omitempty"`
	AccountID              string `json:"account_id"`
	Network                string `json:"network"`
	Type                   string `json:"type"`
	UnreadCount            int64  `json:"unread_count"`
	IsArchived             bool   `json:"is_archived"`
	IsMuted                bool   `json:"is_muted"`
	IsPinned               bool   `json:"is_pinned"`
	LastActivity           string `json:"last_activity,omitempty"`
	LastReadMessageSortKey string `json:"last_read_message_sort_key,omitempty"`
	LocalChatID            string `json:"local_chat_id,omitempty"`
	Preview                string `json:"preview,omitempty"`
	ParticipantsTotal      int64  `json:"participants_total"`
	ParticipantsReturned   int    `json:"participants_returned"`
	ParticipantsHasMore    bool   `json:"participants_has_more"`
}

ChatDetail represents a chat detail response.

type ChatGetParams added in v0.11.0

type ChatGetParams struct {
	MaxParticipantCount *int
}

ChatGetParams configures chat detail retrieval.

type ChatListItem

type ChatListItem struct {
	ID           string `json:"id"`
	Title        string `json:"title"`
	DisplayName  string `json:"display_name,omitempty"`
	AccountID    string `json:"account_id"`
	LastActivity string `json:"last_activity,omitempty"`
	Preview      string `json:"preview,omitempty"`
}

ChatListItem represents a chat in list output.

type ChatListParams

type ChatListParams struct {
	AccountIDs []string
	Cursor     string
	Direction  string // before|after
}

ChatListParams configures chat list queries.

type ChatListResult

type ChatListResult struct {
	Items        []ChatListItem `json:"items"`
	HasMore      bool           `json:"has_more"`
	OldestCursor string         `json:"oldest_cursor,omitempty"`
	NewestCursor string         `json:"newest_cursor,omitempty"`
}

ChatListResult is the list response with pagination info.

type ChatSearchItem

type ChatSearchItem struct {
	ID          string `json:"id"`
	Title       string `json:"title"`
	DisplayName string `json:"display_name,omitempty"`
	AccountID   string `json:"account_id"`
	Type        string `json:"type"`
	Network     string `json:"network"`
	UnreadCount int64  `json:"unread_count"`
	IsArchived  bool   `json:"is_archived"`
	IsMuted     bool   `json:"is_muted"`
}

ChatSearchItem represents a chat in search output.

type ChatSearchParams

type ChatSearchParams struct {
	Query              string
	AccountIDs         []string
	Inbox              string // primary|low-priority|archive
	UnreadOnly         bool
	IncludeMuted       *bool
	LastActivityAfter  *time.Time
	LastActivityBefore *time.Time
	Type               string // direct|group|any
	Scope              string // titles|participants
	Limit              int
	Cursor             string
	Direction          string // before|after
}

ChatSearchParams configures chat search queries.

type ChatSearchResult

type ChatSearchResult struct {
	Items        []ChatSearchItem `json:"items"`
	HasMore      bool             `json:"has_more"`
	OldestCursor string           `json:"oldest_cursor,omitempty"`
	NewestCursor string           `json:"newest_cursor,omitempty"`
}

ChatSearchResult is the search response with pagination info.

type ChatStartParams added in v0.15.0

type ChatStartParams struct {
	AccountID   string
	User        ChatStartUser
	AllowInvite *bool
	MessageText string
}

ChatStartParams configures mode=start chat creation.

type ChatStartResult added in v0.15.0

type ChatStartResult struct {
	ChatID string `json:"chat_id"`
	Status string `json:"status,omitempty"`
}

ChatStartResult is the response from start-mode chat resolution/creation.

type ChatStartUser added in v0.15.0

type ChatStartUser struct {
	ID          string
	Email       string
	FullName    string
	PhoneNumber string
	Username    string
}

ChatStartUser contains merged user hints for start-mode chat creation.

type ChatsService

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

ChatsService handles chat operations.

func (*ChatsService) Archive

func (s *ChatsService) Archive(ctx context.Context, chatID string, archived bool) error

Archive archives or unarchives a chat.

func (*ChatsService) Create added in v0.3.0

Create creates a new chat.

func (*ChatsService) Get

func (s *ChatsService) Get(ctx context.Context, chatID string, params ChatGetParams) (ChatDetail, error)

Get retrieves details for a single chat by ID.

func (*ChatsService) List

List retrieves chats with cursor-based pagination.

func (*ChatsService) Search

Search retrieves chats matching a query.

func (*ChatsService) Start added in v0.15.0

Start resolves or creates a direct chat from merged contact data (mode=start).

type Client

type Client struct {
	SDK *beeperdesktopapi.Client
	// contains filtered or unexported fields
}

Client wraps the Beeper Desktop SDK.

func NewClient

func NewClient(token string, baseURL string, timeout time.Duration) (*Client, error)

NewClient creates a new Beeper API client. Token precedence: BEEPER_TOKEN > BEEPER_ACCESS_TOKEN > provided token URL precedence: BEEPER_URL > BEEPER_DESKTOP_BASE_URL > provided baseURL

func (*Client) Accounts

func (c *Client) Accounts() *AccountsService

Accounts returns the accounts service.

func (*Client) Assets added in v0.4.0

func (c *Client) Assets() *AssetsService

Assets returns the assets service.

func (*Client) Chats

func (c *Client) Chats() *ChatsService

Chats returns the chats service.

func (*Client) Connect added in v0.15.0

func (c *Client) Connect() *ConnectService

Connect returns the connect/discovery service.

func (*Client) Events added in v0.16.0

func (c *Client) Events() *EventsService

Events returns the experimental WebSocket events service.

func (*Client) Focus

func (c *Client) Focus(ctx context.Context, params FocusParams) (FocusResult, error)

Focus brings Beeper Desktop to the foreground, optionally navigating to a chat.

func (*Client) Messages

func (c *Client) Messages() *MessagesService

Messages returns the messages service.

func (*Client) Reminders

func (c *Client) Reminders() *RemindersService

Reminders returns the reminders service.

func (*Client) Search

func (c *Client) Search(ctx context.Context, params SearchParams) (SearchResult, error)

Search performs a global search across chats and messages. If message pagination params are provided, it uses /v1/messages/search for the message results while still using /v1/search for chats/groups.

type ConnectInfo added in v0.15.0

type ConnectInfo struct {
	Name      string            `json:"name,omitempty"`
	Version   string            `json:"version,omitempty"`
	Runtime   string            `json:"runtime,omitempty"`
	Endpoints map[string]string `json:"endpoints,omitempty"`
	Raw       map[string]any    `json:"raw,omitempty"`
}

ConnectInfo is metadata returned by GET /v1/info.

type ConnectService added in v0.15.0

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

ConnectService handles connect discovery and token introspection endpoints.

func (*ConnectService) Info added in v0.15.0

Info retrieves connect metadata for the running Beeper Desktop API server.

func (*ConnectService) Introspect added in v0.15.0

func (s *ConnectService) Introspect(ctx context.Context, token string) (TokenIntrospection, error)

Introspect checks token activity and metadata via OAuth introspection.

type Contact added in v0.3.0

type Contact struct {
	ID            string `json:"id"`
	FullName      string `json:"full_name,omitempty"`
	Username      string `json:"username,omitempty"`
	Email         string `json:"email,omitempty"`
	PhoneNumber   string `json:"phone_number,omitempty"`
	CannotMessage bool   `json:"cannot_message,omitempty"`
	ImgURL        string `json:"img_url,omitempty"`
}

Contact represents a contact search result.

type ContactListParams added in v0.15.0

type ContactListParams struct {
	Cursor    string
	Direction string // before|after
}

ContactListParams configures cursor-based contacts list queries.

type ContactListResult added in v0.15.0

type ContactListResult struct {
	Items        []Contact `json:"items"`
	HasMore      bool      `json:"has_more"`
	OldestCursor string    `json:"oldest_cursor,omitempty"`
	NewestCursor string    `json:"newest_cursor,omitempty"`
}

ContactListResult is the contacts list response with pagination info.

type EditParams added in v0.10.0

type EditParams struct {
	Text string
}

EditParams configures message edit requests.

type EditResult added in v0.10.0

type EditResult struct {
	ChatID    string `json:"chat_id"`
	MessageID string `json:"message_id"`
	Success   bool   `json:"success"`
}

EditResult is the response from editing a message.

type Event added in v0.16.0

type Event struct {
	Type      string           `json:"type"`
	Version   int64            `json:"version,omitempty"`
	RequestID string           `json:"requestID,omitempty"`
	Code      string           `json:"code,omitempty"`
	Message   string           `json:"message,omitempty"`
	ChatIDs   []string         `json:"chatIDs,omitempty"`
	Seq       int64            `json:"seq,omitempty"`
	TS        int64            `json:"ts,omitempty"`
	ChatID    string           `json:"chatID,omitempty"`
	IDs       []string         `json:"ids,omitempty"`
	Entries   []map[string]any `json:"entries,omitempty"`
	Raw       map[string]any   `json:"-"`
}

Event is a normalized payload for both control and domain messages.

func (Event) IsControlMessage added in v0.16.0

func (e Event) IsControlMessage() bool

IsControlMessage reports whether the event is one of the protocol control messages.

type EventsConnection added in v0.16.0

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

EventsConnection wraps an active websocket connection.

func (*EventsConnection) Close added in v0.16.0

func (c *EventsConnection) Close() error

Close closes the websocket connection.

func (*EventsConnection) ReadEvent added in v0.16.0

func (c *EventsConnection) ReadEvent(ctx context.Context) (Event, error)

ReadEvent reads one websocket event payload.

func (*EventsConnection) SetSubscriptions added in v0.16.0

func (c *EventsConnection) SetSubscriptions(ctx context.Context, requestID string, chatIDs []string) error

SetSubscriptions replaces current websocket subscriptions.

type EventsHandshakeError added in v0.16.0

type EventsHandshakeError struct {
	StatusCode int
	Status     string
	Err        error
}

EventsHandshakeError is returned when opening /v1/ws fails at HTTP handshake time.

func (*EventsHandshakeError) Error added in v0.16.0

func (e *EventsHandshakeError) Error() string

func (*EventsHandshakeError) Unwrap added in v0.16.0

func (e *EventsHandshakeError) Unwrap() error

Unwrap returns the underlying dial error.

type EventsService added in v0.16.0

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

EventsService handles experimental WebSocket live events.

func (*EventsService) Connect added in v0.16.0

func (s *EventsService) Connect(ctx context.Context) (*EventsConnection, error)

Connect opens an authenticated websocket to /v1/ws.

type FocusParams

type FocusParams struct {
	ChatID              string
	MessageID           string
	DraftText           string
	DraftAttachmentPath string
}

FocusParams configures focus requests.

type FocusResult

type FocusResult struct {
	Success bool `json:"success"`
}

FocusResult is the response from focusing the app.

type MessageAttachment added in v0.7.0

type MessageAttachment struct {
	Type        string  `json:"type,omitempty"`
	FileName    string  `json:"file_name,omitempty"`
	FileSize    int64   `json:"file_size,omitempty"`
	MimeType    string  `json:"mime_type,omitempty"`
	SrcURL      string  `json:"src_url,omitempty"`
	Duration    float64 `json:"duration,omitempty"`
	IsGif       bool    `json:"is_gif,omitempty"`
	IsSticker   bool    `json:"is_sticker,omitempty"`
	IsVoiceNote bool    `json:"is_voice_note,omitempty"`
	PosterImg   string  `json:"poster_img,omitempty"`
	Width       int     `json:"width,omitempty"`
	Height      int     `json:"height,omitempty"`
}

MessageAttachment represents a message attachment.

type MessageItem

type MessageItem struct {
	ID                    string              `json:"id"`
	AccountID             string              `json:"account_id,omitempty"`
	ChatID                string              `json:"chat_id"`
	SenderID              string              `json:"sender_id,omitempty"`
	SenderName            string              `json:"sender_name,omitempty"`
	Text                  string              `json:"text,omitempty"`
	MessageType           string              `json:"message_type,omitempty"`
	Timestamp             string              `json:"timestamp,omitempty"`
	SortKey               string              `json:"sort_key,omitempty"`
	LinkedMessageID       string              `json:"linked_message_id,omitempty"`
	IsSender              bool                `json:"is_sender,omitempty"`
	IsUnread              bool                `json:"is_unread,omitempty"`
	HasMedia              bool                `json:"has_media,omitempty"`
	Attachments           []MessageAttachment `json:"attachments,omitempty"`
	Reactions             []MessageReaction   `json:"reactions,omitempty"`
	ReactionKeys          []string            `json:"reaction_keys,omitempty"`
	DownloadedAttachments []string            `json:"downloaded_attachments,omitempty"`
}

MessageItem represents a message in list/search output.

type MessageListParams

type MessageListParams struct {
	Cursor    string
	Direction string // before|after
}

MessageListParams configures message list queries.

type MessageListResult

type MessageListResult struct {
	Items      []MessageItem `json:"items"`
	HasMore    bool          `json:"has_more"`
	NextCursor string        `json:"next_cursor,omitempty"`
}

MessageListResult is the list response with pagination info.

type MessageReaction added in v0.7.0

type MessageReaction struct {
	ID            string `json:"id,omitempty"`
	ParticipantID string `json:"participant_id,omitempty"`
	ReactionKey   string `json:"reaction_key,omitempty"`
	Emoji         bool   `json:"emoji,omitempty"`
	ImgURL        string `json:"img_url,omitempty"`
}

MessageReaction represents a reaction on a message.

type MessageSearchParams

type MessageSearchParams struct {
	Query              string
	AccountIDs         []string
	ChatIDs            []string
	ChatType           string // group|single
	Sender             string // me|others|<user-id>
	MediaTypes         []string
	DateAfter          *time.Time
	DateBefore         *time.Time
	IncludeMuted       *bool
	ExcludeLowPriority *bool
	Cursor             string
	Direction          string // before|after
	Limit              int
}

MessageSearchParams configures message search queries.

type MessageSearchResult

type MessageSearchResult struct {
	Items        []MessageItem `json:"items"`
	HasMore      bool          `json:"has_more"`
	OldestCursor string        `json:"oldest_cursor,omitempty"`
	NewestCursor string        `json:"newest_cursor,omitempty"`
}

MessageSearchResult is the search response with pagination info.

type MessagesService

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

MessagesService handles message operations.

func (*MessagesService) Edit added in v0.10.0

func (s *MessagesService) Edit(ctx context.Context, chatID, messageID string, params EditParams) (EditResult, error)

Edit updates the text content of an existing message.

func (*MessagesService) List

List retrieves messages for a chat with cursor-based pagination.

func (*MessagesService) React added in v0.15.0

func (s *MessagesService) React(ctx context.Context, chatID, messageID, reactionKey string) error

React adds a reaction to a message.

func (*MessagesService) Search

Search retrieves messages matching a query.

func (*MessagesService) Send

func (s *MessagesService) Send(ctx context.Context, chatID string, params SendParams) (SendResult, error)

Send sends a text message to a chat.

func (*MessagesService) Unreact added in v0.15.0

func (s *MessagesService) Unreact(ctx context.Context, chatID, messageID, reactionKey string) error

Unreact removes a reaction from a message.

type RemindersService

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

RemindersService handles reminder operations.

func (*RemindersService) Clear

func (s *RemindersService) Clear(ctx context.Context, chatID string) error

Clear removes a reminder from a chat.

func (*RemindersService) Set

func (s *RemindersService) Set(ctx context.Context, chatID string, params SetParams) error

Set creates a reminder for a chat.

type SearchChat

type SearchChat struct {
	ID          string `json:"id"`
	Title       string `json:"title"`
	DisplayName string `json:"display_name,omitempty"`
	Type        string `json:"type"`
	Network     string `json:"network"`
	AccountID   string `json:"account_id"`
	UnreadCount int64  `json:"unread_count"`
}

SearchChat represents a chat in search results.

type SearchMessages

type SearchMessages struct {
	Items        []MessageItem `json:"items"`
	HasMore      bool          `json:"has_more"`
	OldestCursor string        `json:"oldest_cursor,omitempty"`
	NewestCursor string        `json:"newest_cursor,omitempty"`
}

SearchMessages represents message results from global search.

type SearchParams

type SearchParams struct {
	Query             string
	MessagesCursor    string
	MessagesDirection string // before|after
	MessagesLimit     int
}

SearchParams configures global search behavior.

type SearchResult

type SearchResult struct {
	Chats    []SearchChat   `json:"chats"`
	InGroups []SearchChat   `json:"in_groups"`
	Messages SearchMessages `json:"messages"`
}

SearchResult is the response from global search.

type SendAttachmentParams added in v0.10.0

type SendAttachmentParams struct {
	UploadID string
	FileName string
	MimeType string
	Type     string
	Duration *float64
	Width    *float64
	Height   *float64
}

SendAttachmentParams configures attachment payload values for message send.

type SendParams

type SendParams struct {
	Text             string
	ReplyToMessageID string
	Attachment       *SendAttachmentParams
}

SendParams configures message send requests.

type SendResult

type SendResult struct {
	ChatID           string `json:"chat_id"`
	PendingMessageID string `json:"pending_message_id"`
}

SendResult is the response from sending a message.

type SetParams

type SetParams struct {
	RemindAt                 time.Time
	DismissOnIncomingMessage bool
}

SetParams configures reminder set requests.

type TokenIntrospection added in v0.15.0

type TokenIntrospection struct {
	Active    bool           `json:"active"`
	Scope     string         `json:"scope,omitempty"`
	ClientID  string         `json:"client_id,omitempty"`
	Subject   string         `json:"subject,omitempty"`
	Username  string         `json:"username,omitempty"`
	TokenType string         `json:"token_type,omitempty"`
	Issuer    string         `json:"issuer,omitempty"`
	ExpiresAt int64          `json:"expires_at,omitempty"`
	IssuedAt  int64          `json:"issued_at,omitempty"`
	NotBefore int64          `json:"not_before,omitempty"`
	Raw       map[string]any `json:"raw,omitempty"`
}

TokenIntrospection is metadata returned by POST /oauth/introspect.

Jump to

Keyboard shortcuts

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