madon

package module
v1.6.0 Latest Latest
Warning

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

 Go to latest Published: May 28, 2017 License: MIT Imports: 18 Imported by: 0

README

madon

Golang library for the Mastodon API

godoc license build Go Report Card

madon is a Go library to access the Mastondon REST API.

This implementation covers 100% of the current API, including the streaming API.

The madonctl console client uses this library exhaustively.

Installation

To install the library (Go >= v1.5 required):

go get github.com/McKael/madon

You can test it with my CLI tool:

go get github.com/McKael/madonctl

Usage

This section has not been written yet (PR welcome).

For now please check godoc and check the madonctl project implementation.

History

This API implementation was initially submitted as a PR for gondole.

The repository is actually a fork of my gondole branch so that history and credits are preserved.

References

Documentation

Index

Constants

View Source 
const (
	// MadonVersion contains the version of the Madon library
	MadonVersion = "1.6.0"

	// NoRedirect is the URI for no redirection in the App registration
	NoRedirect = "urn:ietf:wg:oauth:2.0:oob"
)

Variables

View Source 
var (
	ErrUninitializedClient = errors.New("use of uninitialized madon client")
	ErrAlreadyRegistered   = errors.New("app already registered")
	ErrEntityNotFound      = errors.New("entity not found")
	ErrInvalidParameter    = errors.New("incorrect parameter")
	ErrInvalidID           = errors.New("incorrect entity ID")
)

Error codes

Functions

This section is empty.

Types

type Account 

type Account struct {
	ID             int64     `json:"id"`
	Username       string    `json:"username"`
	Acct           string    `json:"acct"`
	DisplayName    string    `json:"display_name"`
	Note           string    `json:"note"`
	URL            string    `json:"url"`
	Avatar         string    `json:"avatar"`
	AvatarStatic   string    `json:"avatar_static"`
	HeaderStatic   string    `json:"header_static"`
	Locked         bool      `json:"locked"`
	CreatedAt      time.Time `json:"created_at"`
	FollowersCount int64     `json:"followers_count"`
	FollowingCount int64     `json:"following_count"`
	StatusesCount  int64     `json:"statuses_count"`
}

Account represents a Mastodon account entity

type Application 

type Application struct {
	Name    string `json:"name"`
	Website string `json:"website"`
}

Application represents a Mastodon application entity

type Attachment 

type Attachment struct {
	ID         int64   `json:"id"`
	Type       string  `json:"type"`
	URL        string  `json:"url"`
	RemoteURL  *string `json:"remote_url"`
	PreviewURL string  `json:"preview_url"`
	TextURL    *string `json:"text_url"`
	Meta       *struct {
		Original struct {
			Size   string  `json:"size"`
			Aspect float64 `json:"aspect"`
			Width  int     `json:"width"`
			Height int     `json:"height"`
		} `json:"original"`
		Small struct {
			Size   string  `json:"size"`
			Aspect float64 `json:"aspect"`
			Width  int     `json:"width"`
			Height int     `json:"height"`
		} `json:"small"`
	} `json:"meta"`
}

Attachment represents a Mastodon attachement entity

type Card 

type Card struct {
	URL          string  `json:"url"`
	Title        string  `json:"title"`
	Description  string  `json:"description"`
	Image        string  `json:"image"`
	Type         *string `json:"type"`
	AuthorName   *string `json:"author_name"`
	AuthorURL    *string `json:"author_url"`
	ProviderName *string `json:"provider_name"`
	ProviderURL  *string `json:"provider_url"`
	HTML         *string `json:"html"`
	Width        *int    `json:"width"`
	Height       *int    `json:"height"`
}

Card represents a Mastodon card entity

type Client 

type Client struct {
	Name        string // Name of the client
	ID          string // Application ID
	Secret      string // Application secret
	APIBase     string // API prefix URL
	InstanceURL string // Instance base URL

	UserToken *UserToken // User token
}

Client contains data for a madon client application

func NewApp 

func NewApp(name, website string, scopes []string, redirectURI, instanceName string) (mc *Client, err error)

NewApp registers a new application with a given instance

func RestoreApp 

func RestoreApp(name, instanceName, appID, appSecret string, userToken *UserToken) (mc *Client, err error)

RestoreApp recreates an application client with existing secrets

func (*Client) BlockAccount 

func (mc *Client) BlockAccount(accountID int64) (*Relationship, error)

BlockAccount blocks an account

func (*Client) BlockDomain added in v1.6.0 

func (mc *Client) BlockDomain(domain DomainName) error

BlockDomain blocks the specified domain

func (*Client) ClearNotifications 

func (mc *Client) ClearNotifications() error

ClearNotifications deletes all notifications from the Mastodon server for the authenticated user

func (*Client) DeleteStatus 

func (mc *Client) DeleteStatus(statusID int64) error

DeleteStatus deletes a status

func (*Client) DismissNotification 

func (mc *Client) DismissNotification(notificationID int64) error

DismissNotification deletes a notification

func (*Client) FavouriteStatus 

func (mc *Client) FavouriteStatus(statusID int64) error

FavouriteStatus favourites a status

func (*Client) FollowAccount 

func (mc *Client) FollowAccount(accountID int64) (*Relationship, error)

FollowAccount follows an account

func (*Client) FollowRemoteAccount 

func (mc *Client) FollowRemoteAccount(uri string) (*Account, error)

FollowRemoteAccount follows a remote account The parameter 'uri' is a URI (e.mc. "username@domain").

func (*Client) FollowRequestAuthorize 

func (mc *Client) FollowRequestAuthorize(accountID int64, authorize bool) error

FollowRequestAuthorize authorizes or rejects an account follow-request

func (*Client) GetAccount 

func (mc *Client) GetAccount(accountID int64) (*Account, error)

GetAccount returns an account entity The returned value can be nil if there is an error or if the requested ID does not exist.

func (*Client) GetAccountFollowRequests 

func (mc *Client) GetAccountFollowRequests(lopt *LimitParams) ([]Account, error)

GetAccountFollowRequests returns the list of follow requests accounts The lopt parameter is optional (can be nil).

func (*Client) GetAccountFollowers 

func (mc *Client) GetAccountFollowers(accountID int64, lopt *LimitParams) ([]Account, error)

GetAccountFollowers returns the list of accounts following a given account

func (*Client) GetAccountFollowing 

func (mc *Client) GetAccountFollowing(accountID int64, lopt *LimitParams) ([]Account, error)

GetAccountFollowing returns the list of accounts a given account is following

func (*Client) GetAccountRelationships 

func (mc *Client) GetAccountRelationships(accountIDs []int64) ([]Relationship, error)

GetAccountRelationships returns a list of relationship entities for the given accounts

func (*Client) GetAccountStatuses 

func (mc *Client) GetAccountStatuses(accountID int64, onlyMedia, excludeReplies bool, lopt *LimitParams) ([]Status, error)

GetAccountStatuses returns a list of status entities for the given account If onlyMedia is true, returns only statuses that have media attachments. If excludeReplies is true, skip statuses that reply to other statuses. If lopt.All is true, several requests will be made until the API server has nothing to return. If lopt.Limit is set (and not All), several queries can be made until the limit is reached.

func (*Client) GetBlockedAccounts 

func (mc *Client) GetBlockedAccounts(lopt *LimitParams) ([]Account, error)

GetBlockedAccounts returns the list of blocked accounts The lopt parameter is optional (can be nil).

func (*Client) GetBlockedDomains added in v1.6.0 

func (mc *Client) GetBlockedDomains(lopt *LimitParams) ([]DomainName, error)

GetBlockedDomains returns the current user blocked domains If lopt.All is true, several requests will be made until the API server has nothing to return.

func (*Client) GetCurrentAccount 

func (mc *Client) GetCurrentAccount() (*Account, error)

GetCurrentAccount returns the current user account

func (*Client) GetCurrentInstance 

func (mc *Client) GetCurrentInstance() (*Instance, error)

GetCurrentInstance returns current instance information

func (*Client) GetFavourites 

func (mc *Client) GetFavourites(lopt *LimitParams) ([]Status, error)

GetFavourites returns the list of the user's favourites If lopt.All is true, several requests will be made until the API server has nothing to return. If lopt.Limit is set (and not All), several queries can be made until the limit is reached.

func (*Client) GetMutedAccounts 

func (mc *Client) GetMutedAccounts(lopt *LimitParams) ([]Account, error)

GetMutedAccounts returns the list of muted accounts The lopt parameter is optional (can be nil).

func (*Client) GetNotification 

func (mc *Client) GetNotification(notificationID int64) (*Notification, error)

GetNotification returns a notification The returned notification can be nil if there is an error or if the requested notification does not exist.

func (*Client) GetNotifications 

func (mc *Client) GetNotifications(lopt *LimitParams) ([]Notification, error)

GetNotifications returns the list of the user's notifications If lopt.All is true, several requests will be made until the API server has nothing to return. If lopt.Limit is set (and not All), several queries can be made until the limit is reached.

func (*Client) GetReports 

func (mc *Client) GetReports(lopt *LimitParams) ([]Report, error)

GetReports returns the current user's reports (I don't know if the limit options are used by the API server.)

func (*Client) GetStatus 

func (mc *Client) GetStatus(statusID int64) (*Status, error)

GetStatus returns a status The returned status can be nil if there is an error or if the requested ID does not exist.

func (*Client) GetStatusCard 

func (mc *Client) GetStatusCard(statusID int64) (*Card, error)

GetStatusCard returns a status card

func (*Client) GetStatusContext 

func (mc *Client) GetStatusContext(statusID int64) (*Context, error)

GetStatusContext returns a status context

func (*Client) GetStatusFavouritedBy 

func (mc *Client) GetStatusFavouritedBy(statusID int64, lopt *LimitParams) ([]Account, error)

GetStatusFavouritedBy returns a list of the accounts who favourited a status

func (*Client) GetStatusRebloggedBy 

func (mc *Client) GetStatusRebloggedBy(statusID int64, lopt *LimitParams) ([]Account, error)

GetStatusRebloggedBy returns a list of the accounts who reblogged a status

func (*Client) GetTimelines 

func (mc *Client) GetTimelines(timeline string, local bool, lopt *LimitParams) ([]Status, error)

GetTimelines returns a timeline (a list of statuses timeline can be "home", "public", or a hashtag (use ":hashtag" or "#hashtag") For the public timelines, you can set 'local' to true to get only the local instance. If lopt.All is true, several requests will be made until the API server has nothing to return. If lopt.Limit is set (and not All), several queries can be made until the limit is reached.

func (*Client) LoginBasic 

func (mc *Client) LoginBasic(username, password string, scopes []string) error

LoginBasic does basic user authentication

func (*Client) LoginOAuth2 added in v1.5.0 

func (mc *Client) LoginOAuth2(code string, scopes []string) (string, error)

LoginOAuth2 handles OAuth2 authentication If code is empty, the URL to the server consent page will be returned; if not, the user token is set.

func (*Client) MuteAccount 

func (mc *Client) MuteAccount(accountID int64) (*Relationship, error)

MuteAccount mutes an account

func (*Client) MuteConversation added in v1.6.0 

func (mc *Client) MuteConversation(statusID int64) (*Status, error)

MuteConversation mutes the conversation containing a status

func (*Client) PostStatus 

func (mc *Client) PostStatus(text string, inReplyTo int64, mediaIDs []int64, sensitive bool, spoilerText string, visibility string) (*Status, error)

PostStatus posts a new "toot" All parameters but "text" can be empty. Visibility must be empty, or one of "direct", "private", "unlisted" and "public".

func (*Client) ReblogStatus 

func (mc *Client) ReblogStatus(statusID int64) error

ReblogStatus reblogs a status

func (*Client) ReportUser 

func (mc *Client) ReportUser(accountID int64, statusIDs []int64, comment string) (*Report, error)

ReportUser reports the user account

func (*Client) Search 

func (mc *Client) Search(query string, resolve bool) (*Results, error)

Search search for contents (accounts or statuses) and returns a Results

func (*Client) SearchAccounts 

func (mc *Client) SearchAccounts(query string, lopt *LimitParams) ([]Account, error)

SearchAccounts returns a list of accounts matching the query string The lopt parameter is optional (can be nil) or can be used to set a limit.

func (*Client) SetUserToken 

func (mc *Client) SetUserToken(token, username, password string, scopes []string) error

SetUserToken sets an existing user credentials No verification of the arguments is made.

func (*Client) StreamListener 

func (mc *Client) StreamListener(name, hashTag string, events chan<- StreamEvent, stopCh <-chan bool, doneCh chan bool) error

StreamListener listens to a stream from the Mastodon server The stream 'name' can be "user", "local", "public" or "hashtag". For 'hashtag', the hashTag argument cannot be empty. The events are sent to the events channel (the errors as well). The streaming is terminated if the 'stopCh' channel is closed. The 'doneCh' channel is closed if the connection is closed by the server. Please note that this method launches a goroutine to listen to the events.

func (*Client) UnblockAccount 

func (mc *Client) UnblockAccount(accountID int64) (*Relationship, error)

UnblockAccount unblocks an account

func (*Client) UnblockDomain added in v1.6.0 

func (mc *Client) UnblockDomain(domain DomainName) error

UnblockDomain unblocks the specified domain

func (*Client) UnfavouriteStatus 

func (mc *Client) UnfavouriteStatus(statusID int64) error

UnfavouriteStatus unfavourites a status

func (*Client) UnfollowAccount 

func (mc *Client) UnfollowAccount(accountID int64) (*Relationship, error)

UnfollowAccount unfollows an account

func (*Client) UnmuteAccount 

func (mc *Client) UnmuteAccount(accountID int64) (*Relationship, error)

UnmuteAccount unmutes an account

func (*Client) UnmuteConversation added in v1.6.0 

func (mc *Client) UnmuteConversation(statusID int64) (*Status, error)

UnmuteConversation unmutes the conversation containing a status

func (*Client) UnreblogStatus 

func (mc *Client) UnreblogStatus(statusID int64) error

UnreblogStatus unreblogs a status

func (*Client) UpdateAccount 

func (mc *Client) UpdateAccount(displayName, note, avatar, headerImage *string) (*Account, error)

UpdateAccount updates the connected user's account data The fields avatar & headerImage can contain base64-encoded images; if they do not (that is; if they don't contain ";base64,"), they are considered as file paths and their content will be encoded. All fields can be nil, in which case they are not updated. displayName and note can be set to "" to delete previous values; I'm not sure images can be deleted -- only replaced AFAICS.

func (*Client) UploadMedia 

func (mc *Client) UploadMedia(filePath string) (*Attachment, error)

UploadMedia uploads the given file and returns an attachment

type Context 

type Context struct {
	Ancestors   []Status `json:"ancestors"`
	Descendants []Status `json:"descendants"`
}

Context represents a Mastodon context entity

type DomainName added in v1.6.0 

type DomainName string

DomainName is a domain name string, as returned by the domain_blocks API

type Error 

type Error struct {
	Text string `json:"error"`
}

Error represents a Mastodon error entity

type Instance 

type Instance struct {
	URI         string `json:"uri"`
	Title       string `json:"title"`
	Description string `json:"description"`
	Email       string `json:"email"`
	Version     string `json:"version"`
}

Instance represents a Mastodon instance entity

type LimitParams 

type LimitParams struct {
	Limit          int   // Number of items per query
	SinceID, MaxID int64 // Boundaries
	All            bool  // Get as many items as possible
}

LimitParams contains common limit/paging options for the Mastodon REST API

type Mention 

type Mention struct {
	ID       int64  `json:"id"`
	URL      string `json:"url"`
	Username string `json:"username"`
	Acct     string `json:"acct"`
}

Mention represents a Mastodon mention entity

type Notification 

type Notification struct {
	ID        int64     `json:"id"`
	Type      string    `json:"type"`
	CreatedAt time.Time `json:"created_at"`
	Account   *Account  `json:"account"`
	Status    *Status   `json:"status"`
}

Notification represents a Mastodon notification entity

type Relationship 

type Relationship struct {
	ID             int64 `json:"id"`
	Following      bool  `json:"following"`
	FollowedBy     bool  `json:"followed_by"`
	Blocking       bool  `json:"blocking"`
	Muting         bool  `json:"muting"`
	Requested      bool  `json:"requested"`
	DomainBlocking bool  `jsin:"domain_blocking"`
}

Relationship represents a Mastodon relationship entity

type Report 

type Report struct {
	ID          int64  `json:"id"`
	ActionTaken string `json:"action_taken"`
}

Report represents a Mastodon report entity

type Results 

type Results struct {
	Accounts []Account `json:"accounts"`
	Statuses []Status  `json:"statuses"`
	Hashtags []string  `json:"hashtags"`
}

Results represents a Mastodon results entity

type Status 

type Status struct {
	ID                 int64        `json:"id"`
	URI                string       `json:"uri"`
	URL                string       `json:"url"`
	Account            *Account     `json:"account"`
	InReplyToID        int64        `json:"in_reply_to_id"`
	InReplyToAccountID int64        `json:"in_reply_to_account_id"`
	Reblog             *Status      `json:"reblog"`
	Content            string       `json:"content"`
	CreatedAt          time.Time    `json:"created_at"`
	ReblogsCount       int64        `json:"reblogs_count"`
	FavouritesCount    int64        `json:"favourites_count"`
	Reblogged          bool         `json:"reblogged"`
	Favourited         bool         `json:"favourited"`
	Muted              bool         `json:"muted"`
	Sensitive          bool         `json:"sensitive"`
	SpoilerText        string       `json:"spoiler_text"`
	Visibility         string       `json:"visibility"`
	MediaAttachments   []Attachment `json:"media_attachments"`
	Mentions           []Mention    `json:"mentions"`
	Tags               []Tag        `json:"tags"`
	Application        Application  `json:"application"`
	Language           string       `json:"language"`
}

Status represents a Mastodon status entity

type StreamEvent 

type StreamEvent struct {
	Event string      // Name of the event (error, update, notification or delete)
	Data  interface{} // Status, Notification or status ID
	Error error       // Error message from the StreamListener
}

StreamEvent contains a single event from the streaming API

type Tag 

type Tag struct {
	Name string `json:"name"`
	URL  string `json:"url"`
}

Tag represents a Mastodon tag entity

type UserToken 

type UserToken struct {
	AccessToken string `json:"access_token"`
	CreatedAt   int64  `json:"created_at"`
	Scope       string `json:"scope"`
	TokenType   string `json:"token_type"`
}

UserToken represents a user token as returned by the Mastodon API

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.