mastodon

Documentation

Overview

Package mastodon is an API client for Mastodon1, specifically designed for making bots.

Index

• type Account
• type Announcement
• type Application
• type Attachment
• type Card
• type Client
  • func Authenticated(botName, botURL, instanceURL, token string) (*Client, error)
  • func Unauthenticated(botName, botURL, instanceURL string) (*Client, error)
  • func (c *Client) AuthorizeURL(app *OAuth2Application, scope string) (string, error)
  • func (c *Client) CreateApplication(ctx context.Context, car CreateApplicationRequest) (*OAuth2Application, error)
  • func (c *Client) CreateStatus(ctx context.Context, csp CreateStatusParams) (*Status, error)
  • func (c *Client) FetchToken(ctx context.Context, app *OAuth2Application, code, scope string) (*TokenInfo, error)
  • func (c *Client) StreamMessages(ctx context.Context, subreq ...WSSubscribeRequest) (chan WSMessage, error)
  • func (c *Client) UploadMedia(ctx context.Context, fin io.Reader, fname, description, focus string) (*Attachment, error)
  • func (c *Client) VerifyCredentials(ctx context.Context) error
• type Context
• type Conversation
• type CreateApplicationRequest
• type CreateStatusParams
  • func (csp CreateStatusParams) Values() url.Values
• type DomainName
• type Emoji
• type EmojiReaction
• type Error
• type Field
• type Instance
• type InstancePeer
• type List
• type MastodonDate
  • func (act *MastodonDate) MarshalJSON() ([]byte, error)
  • func (act *MastodonDate) UnmarshalJSON(b []byte) error
• type Mention
• type Notification
• type OAuth2Application
• type Relationship
• type Report
• type Results
• type SourceParams
• type Status
  • func FetchStatus(ctx context.Context, statusURL string) (*Status, error)
  • func (s Status) ContentText(ctx context.Context) (string, error)
• type Tag
• type TokenInfo
• type WSMessage
• type WSSubscribeRequest
• type WeekActivity

Types

type Account

type Account struct {
	ID             string        `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"`
	Header         string        `json:"header"`
	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"`
	Moved          *Account      `json:"moved"`
	Bot            bool          `json:"bot"`
	Emojis         []Emoji       `json:"emojis"`
	Fields         *[]Field      `json:"fields"`
	Source         *SourceParams `json:"source"`
}

Account represents a Mastodon account entity

type Announcement

type Announcement struct {
	ID          string     `json:"id"`
	Content     string     `json:"content"`
	StartsAt    *time.Time `json:"starts_at"`
	EndsAt      *time.Time `json:"ends_at"`
	AllDay      bool       `json:"all_day"`
	PublishedAt time.Time  `json:"published_at"`
	UpdatedAt   *time.Time `json:"updated_at"`
	Read        bool       `json:"read"`
}

Announcement is a single server announcement.

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         string  `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"`
	Description *string `json:"description"`
}

Attachment represents a Mastodon media attachment 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"`
	EmbedURL     *string `json:"embed_url"`
	HTML         *string `json:"html"`
	Width        *int    `json:"width"`
	Height       *int    `json:"height"`
}

Card represents a Mastodon preview card entity

type Client

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

Client is the client for Mastodon

func Authenticated

func Authenticated(botName, botURL, instanceURL, token string) (*Client, error)

Authenticated makes a new authenticated Mastodon client.

func Unauthenticated

func Unauthenticated(botName, botURL, instanceURL string) (*Client, error)

Unauthenticated makes a new unauthenticated Mastodon client.

func (*Client) AuthorizeURL

func (c *Client) AuthorizeURL(app *OAuth2Application, scope string) (string, error)

func (*Client) CreateApplication

func (c *Client) CreateApplication(ctx context.Context, car CreateApplicationRequest) (*OAuth2Application, error)

func (*Client) CreateStatus

func (c *Client) CreateStatus(ctx context.Context, csp CreateStatusParams) (*Status, error)

func (*Client) FetchToken

func (c *Client) FetchToken(ctx context.Context, app *OAuth2Application, code, scope string) (*TokenInfo, error)

func (*Client) StreamMessages

func (c *Client) StreamMessages(ctx context.Context, subreq ...WSSubscribeRequest) (chan WSMessage, error)

StreamMessages is a low-level message streaming facility.

func (*Client) UploadMedia

func (c *Client) UploadMedia(ctx context.Context, fin io.Reader, fname, description, focus string) (*Attachment, error)

func (*Client) VerifyCredentials

func (c *Client) VerifyCredentials(ctx context.Context) error

type Context

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

Context represents a Mastodon context entity

type Conversation

type Conversation struct {
	ID         string    `json:"id"`
	Unread     bool      `json:"unread"`
	Accounts   []Account `json:"accounts"`
	LastStatus *Status   `json:"status"`
}

Conversation represents a conversation with "direct message" visibility.

type CreateApplicationRequest

type CreateApplicationRequest struct {
	ClientName   string `json:"client_name"`
	RedirectURIs string `json:"redirect_uris"`
	Scopes       string `json:"scopes"`
	Website      string `json:"website"`
}

type CreateStatusParams

type CreateStatusParams struct {
	Status      string     `json:"status"`
	InReplyTo   string     `json:"in_reply_to_id"`
	MediaIDs    []string   `json:"media_ids"`
	SpoilerText string     `json:"spoiler_text"`
	Visibility  string     `json:"visibility"`
	ScheduledAt *time.Time `json:"scheduled_at,omitempty"`
}

func (CreateStatusParams) Values

func (csp CreateStatusParams) Values() url.Values

type DomainName

type DomainName string

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

type Emoji

type Emoji struct {
	ShortCode       string `json:"shortcode"`
	URL             string `json:"url"`
	StaticURL       string `json:"static_url"`
	VisibleInPicker bool   `json:"visible_in_picker"`
}

Emoji represents a Mastodon emoji entity

type EmojiReaction

type EmojiReaction struct {
	Name           string `json:"name"`
	Count          int    `json:"count"`
	AnnouncementID string `json:"announcement_id"`
}

EmojiReaction represents an emoji reaction to an announcement.

type Error

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

Error represents a Mastodon error entity

type Field

type Field struct {
	Name  string `json:"name"`
	Value string `json:"value"`
}

Field is a single field structure (Used for the verify_credentials endpoint)

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"`

	URLs struct {
		SteamingAPI string `json:"streaming_api"`
	} `json:"urls"`
	Stats struct {
		UserCount   int64 `json:"user_count"`
		StatusCount int64 `json:"status_count"`
		DomainCount int64 `json:"domain_count"`
	} `json:"stats"`
	Thumbnail      *string  `json:"thumbnail"`
	Languages      []string `json:"languages"`
	ContactAccount *Account `json:"contact_account"`
}

Instance represents a Mastodon instance entity

type InstancePeer

type InstancePeer string

InstancePeer is a peer name, as returned by the instance/peers API

type List

type List struct {
	ID    string `json:"id"`
	Title string `json:"title"`
}

List represents a Mastodon list entity

type MastodonDate

type MastodonDate struct {
	time.Time
}

MastodonDate is a custom type for the timestamps returned by some API calls It is used, for example, by 'v1/instance/activity' and 'v2/search'. The date returned by those Mastodon API calls is a string containing a timestamp in seconds

func (*MastodonDate) MarshalJSON

func (act *MastodonDate) MarshalJSON() ([]byte, error)

MarshalJSON handles serialization for custom MastodonDate type

func (*MastodonDate) UnmarshalJSON

func (act *MastodonDate) UnmarshalJSON(b []byte) error

UnmarshalJSON handles deserialization for custom MastodonDate type

type Mention

type Mention struct {
	ID       string `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        string    `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 OAuth2Application

type OAuth2Application struct {
	ID           string `json:"id"`
	Name         string `json:"name"`
	Website      string `json:"website"`
	RedirectURI  string `json:"redirect_uri"`
	ClientID     string `json:"client_id"`
	ClientSecret string `json:"client_secret"`
	VapidKey     string `json:"vapid_key"`
}

type Relationship

type Relationship struct {
	ID        string `json:"id"`
	Following bool   `json:"following"`
	//ShowingReblogs      bool  `json:"showing_reblogs"` // Incoherent type
	FollowedBy          bool `json:"followed_by"`
	Blocking            bool `json:"blocking"`
	Muting              bool `json:"muting"`
	Requested           bool `json:"requested"`
	DomainBlocking      bool `jsin:"domain_blocking"`
	MutingNotifications bool `json:"muting_notifications"`
	ShowingReblogs      bool `json:"showing_reblogs"`
	Endorsed            bool `json:"endorsed"`
}

Relationship represents a Mastodon relationship entity

type Report

type Report struct {
	ID          string `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 []Tag     `json:"hashtags"`
}

Results represents a Mastodon search results entity

type SourceParams

type SourceParams struct {
	Privacy   *string  `json:"privacy,omitempty"`
	Language  *string  `json:"language,omitempty"`
	Sensitive *bool    `json:"sensitive,omitempty"`
	Note      *string  `json:"note,omitempty"`
	Fields    *[]Field `json:"fields,omitempty"`
}

SourceParams is a source params structure

type Status

type Status struct {
	ID                 string       `json:"id"`
	URI                string       `json:"uri"`
	URL                string       `json:"url"`
	Account            *Account     `json:"account"`
	InReplyToID        *string      `json:"in_reply_to_id"`
	InReplyToAccountID *string      `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"`
	RepliesCount       int64        `json:"replies_count"`
	Reblogged          bool         `json:"reblogged"`
	Favourited         bool         `json:"favourited"`
	Muted              bool         `json:"muted"`
	Pinned             bool         `json:"pinned"`
	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"`
	Emojis             []Emoji      `json:"emojis"`
	Application        *Application `json:"application"`
	Language           *string      `json:"language"`
}

Status represents a Mastodon status entity

func FetchStatus

func FetchStatus(ctx context.Context, statusURL string) (*Status, error)

FetchStatus fetches a Mastodon status over the internet using the federation protocol.

This will not work if the target server has "secure" mode enabled.

func (Status) ContentText

func (s Status) ContentText(ctx context.Context) (string, error)

ContentText attempts to convert the Status content to plain text using package mastosan.

type Tag

type Tag struct {
	Name    string `json:"name"`
	URL     string `json:"url"`
	History []struct {
		Day      MastodonDate `json:"day"`
		Uses     int64        `json:"uses,string"`
		Accounts int64        `json:"accounts,string"`
	} `json:"history"`
}

Tag represents a Mastodon tag entity

type TokenInfo

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

type WSMessage

type WSMessage struct {
	Stream  []string `json:"stream"`
	Event   string   `json:"event"`
	Payload string   `json:"payload"` // json string
}

WSMessage is a websocket message. Whenever you get something from the streaming service, it will fit into this box.

type WSSubscribeRequest

type WSSubscribeRequest struct {
	Type    string `json:"type"` // should be "subscribe" or "unsubscribe"
	Stream  string `json:"stream"`
	Hashtag string `json:"hashtag,omitempty"`
}

WSSubscribeRequest is a websocket instruction to subscribe to a streaming feed.

type WeekActivity

type WeekActivity struct {
	Week          MastodonDate `json:"week"`
	Statuses      int64        `json:"statuses,string"`
	Logins        int64        `json:"logins,string"`
	Registrations int64        `json:"registrations,string"`
}

WeekActivity represents a Mastodon instance activity "week" entity