gotodon

package module
v1.2.0 Latest Latest
Warning

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

Go to latest
Published: Sep 23, 2019 License: GPL-3.0 Imports: 8 Imported by: 0

README

Gotodon - Managed

Gotodon uses GotodonREST but adds some management to it. Mainly it reduces the amount of repetition you have to do (by writing baseUrl and token.AccessToken) while also providing an object-oriented approach (functions which operate on an object, like lets say liking a status, are performed on a status: someStatus.Favourite(client) )

All repositories which Gotodon consists of:

Features

  • OAuth
    • Authorization Code Flow
    • Password Grant Flow
    • Client Credentials Flow
    • Verifying Application/Access Tokens
    • Revoking Access Tokens
  • All API endpoints as of July 2019

Getting Started

This section will cover everything necessary to get started, from registering a client to getting an access token using any of the three available flows (Authorization Code Flow, Password Grant Flow and Client Credentials Flow)

We start off by declaring constants and globals which will be frequently used in api calls.

const (
    // The address which points to the mastodon instance you want to access
    baseUrl = "domain.tld"
)

// The client which holds any data necessary (combines App and Token)
var client Gotodon

Instantiating the client

First we create an instance of the Gotodon client.

client = CreateClient(

    // The baseUrl, as stated above, is the address of the server to connect to
    baseUrl,

    // These are the scopes we want the client to request when authorizing
    Scopes(ScopeRead, ScopeWrite, ScopeFollow, ScopePush),

    // Here you can set a redirect uri, which will be used when retrieving authorization codes or access token
    "",

    // Filepath is used when storing the client
    "")

Registering the client

After we created the instance, we need to register it as an app.

err = client.Register(

    // The clientName is displayed on statuses on the bottom right (when the status is opened)
    "Gotodon",

    // If a website is set, a user can click on the clientName in a status and it will take him to it.
    "https://gitlab.com/Cyphrags/gotodon-examples/blob/master/managed_example.go")

Authorizing the client

Now that we have registered the app, we need to authorize it. This will grant us an Access Token which will tells the server who is calling and which account the call will effect (i.e. who is posting the status or which profile to update with this nice, new avatar image).

There are three ways to authorize your client:

  1. Authorization Code Flow (ACF)
  2. Password Grant Flow (PGF)
  3. Client Credentials Flow (CCF)

ACF and PGF require that an account already exists. Additionally, ACF requires the user to confirm the app (which removes the to pass any password around which makes it ultimately safer). CCF will create a new account.

These might not be official/commonly used abbreviations. I used them here for simplicities sake.

Scopes

All authorization methods require a set of scopes which will restrict which functions the client can call. You can find a list of scopes in gotodonr/constants.go (and other constants too, like Visibility for statuses).

You should only request the scopes you really need rather than requesting everything. Doing so can reduce the damage caused if an access token is leaked or stolen.

Authorization Code Flow

In the Authorization Code Flow we first generate an URL which the user has to open (this website is the OAuth web endpoint of the mastodon server). The user then needs to confirm that he wants to authorize the app which will present him with an authorization code (using the redirect uri and a local webserver, the authorization code can also be retrieved automatically after the user hit confirm, instead of having them enter it somewhere).

authorizeUrl := client.GetAuthorizeUrl()

// This placeholder variable needs to be filled with the authorization code and how that happens is up to you.
var authorizationCode string

After the user confirmed the authorization request and the authorization code was entered/retrieved, we simply exchange it for an access token (the scope used in GetAuthorizeUrl() and here need to be the same):

err = client.AuthorizeWithAuthorizationCode(authorizationCode)
Password Grant Flow

In the Password Grant Flow we use a login-style flow to get an access token, which means that we simply send the username and password to the server to get an access token.

Requiring a user to login is a potential security risk and/or might scare off some users. In any case, the Authorization Code Flow is preferable (and I strongly advice you to use it).

err = client.AuthorizeWithLoginOnce(

			// The username used to login (usually the e-mail address).
			// How you get the username is up to you (could be hardcoded, through environment variables or by
			// asking the user through a (web-)interface, popup, console, ...)
			username,

			// The password used to login.
			// How you get the password is up to you (could be hardcoded, through environment variables or by
			// asking the user through a (web-)interface, popup, console, ...)
			password)

client provides three AuthorizeWithLogin* methods:

  • AuthorizeWithLogin which retrieves an access token and stores the username and password
  • AuthorizeWithLoginAgain which retrieves an access token if the client has a username and password stored
  • AuthorizeWithLoginOnce which retrieves an access token but doesn't store the username and password

While storing the username and password can be convenient, I strongly advice against it since both are stored as plain text (so please use AuthorizeWithLoginOnce over AuthorizeWithLogin, or use the Authorization Code Flow instead).

Client Credentials Flow

In the Client Credentials Flow we first get a special access token which we then use to create a new account and then get an actual access token for the account we created.

err = client.AuthorizeWithClientCredentials()

This token is not linked to an account and can't be used in any account related methods.

Now we use this token to create a new account.

err = client.CreateAccount(

    // The UserName which is used to "@" this account (@UserName@domain.tld)
    // This is not the displayName, which can always be changed.
    // The userName, however, can only be changed by moving the account.
    username,

    // The email address used for this account. It will receive the initial "confirm your account" email.
    email,

    // The password used to login (in case the client needs to login again or the user wants to login
    // through the web interface, app or another client).
    password,

    // Basically needs to be true and confirms that you agree with the terms and conditions.
    true,

    // The locale which affects the "confirm your account" email
    "en")

CreateAccount might throw an "you can't access this page" error if user registration is disabled

Revoking an Access Token

If you ever need to revoke an access token (i.e. the client is deleted/uninstalled or gets a brand new token) you can simply use the function RevokeToken:

err = client.RevokeAccessToken()

Verifying the client

Now that we have setup the client, we can finally do something with it. To test that everything went alright, we might simply post a status which will tell the world that everything is fine:

client.PostTextStatus("Setup successful", "", false, "", VisibilityPublic, "en", "")

Loading and storing the client

Once a client is created, it can be simply stored to use it again at a later time or after a restart.

err = client.Store(storagePath)

If you want to store the client yourself (i.e. to store it encrypted or with other configuration files), the client can be also be serialized and retrieved as a string.

err, serializedClient = client.ToString()

Now we can load the client again if we need it.

err, client = LoadClient(storagePath)

If you chose to store it yourself, you only need to deserialize it.

err, client = LoadClientFromString(serializedClient)

It is also possible to create a client from an access token. However, this client is incomplete (lacks certain data like the ClientId and ClientSecret) but is enough for normal applications (it can't be used to get an access token though).

err, client = LoadClientFromAccessToken(baseUrl, "ReplaceThisWithAnAccessToken")

storagePath is the full path including the file name, i.e. '/home' would try to create a file 'home' in your root directory. Instead it should read '/home/client.json'.

You can view the full example here: gotodon-examples/managed_example.go

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func GetLocalPath

func GetLocalPath() (string, error)

Returns the path to the directory the go app is executed from

func OpenUrl

func OpenUrl(url string) error

OpenUrl opens the given url in the users default browser.

Kudos to icza (https://stackoverflow.com/a/39324149)

Types

type Gotodon

type Gotodon struct {
	BaseUrl     string `json:"base_url"`
	Scope       string `json:"scope"`
	RedirectUri string `json:"redirect_uri"`
	Filepath    string `json:"-"`
	MApp
	MToken
	Login
}

A Mastodon client API written in Go

func CreateClient

func CreateClient(baseUrl, scope, redirectUri, filepath string) Gotodon

Creates a new client

func CreateDefaultClient

func CreateDefaultClient(baseUrl, filepath string) Gotodon

Creates a new client with default settings

func LoadClient

func LoadClient(path string) (error, Gotodon)

Loads a client from the given path

func LoadClientFromAccessToken

func LoadClientFromAccessToken(baseUrl, accessToken string) (error, Gotodon)

Loads a client from the given baseUrl and accessToken

However, the client lacks various variables (like ClientId, ClientSecret, ...) which prevents all token-related functions (like RevokeToken and all Authorization methods)

func LoadClientFromString

func LoadClientFromString(dat string) (error, Gotodon)

Loads a client from the given string

func (*Gotodon) AuthorizeWithAuthorizationCode

func (client *Gotodon) AuthorizeWithAuthorizationCode(authorizationCode string) error

Exchanges the AuthorizationCode to retrieve an AccessToken for this client

authorizationCode: the authorization code received from the user

Updates the client with a new token

func (*Gotodon) AuthorizeWithClientCredentials

func (client *Gotodon) AuthorizeWithClientCredentials() error

Gets a token by authorizing the application using its client credentials.

scope: space-separated list of scopes to be authorized for

Updates the client with a new token

Note: the token received from this method is an application token, not an account token. It can be used for functions which require an authentication, but will fail for all functions requiring a user (like posting a status, ...). After authorizing this way, use CreateAccount(...) which creates an account which can be used for all those functions (but will fail if the server has account registration turned off).

func (*Gotodon) AuthorizeWithLogin

func (client *Gotodon) AuthorizeWithLogin(username, password string) error

Retrieves an AccessToken for this client by logging in with the login credentials. Stores the username and password, which allows the usage of AuthorizeWithLoginAgain() (storing the username and password is unsafe and it is encouraged to use the authorization code flow instead).

username: username to log in with
password: password to log in with

Updates the client with a new token

func (*Gotodon) AuthorizeWithLoginAgain

func (client *Gotodon) AuthorizeWithLoginAgain() error

Retrieves an AccessToken for this client by using AuthorizeWithLogin(email, password) using the stored username and password (storing the username and password is unsafe and it is encouraged to use the authorization code flow instead).

func (*Gotodon) AuthorizeWithLoginOnce

func (client *Gotodon) AuthorizeWithLoginOnce(username, password string) error

Retrieves an AccessToken for this client by logging in with the login credentials. Does not store the username and password, which prevents the usage of AuthorizeWithLoginAgain() (this won't store the username and password which makes it safer than AuthorizeWithLogin, but it is encouraged to use the authorization code flow instead).

username: username to log in with
password: password to log in with

Updates the client with a new token

func (*Gotodon) BlockDomain

func (client *Gotodon) BlockDomain(domain string) error

Blocks the given domain (strip any protocols and such, domain needs to be 'domain.tld')

domain: the domain to be blocked

func (*Gotodon) ClearNotifications

func (client *Gotodon) ClearNotifications() error

Clear all notifications

func (*Gotodon) CreateAccount

func (client *Gotodon) CreateAccount(username, email, password string, agreement bool, locale string) error

Creates a new account with the given username, email and password.

This can only be used when the client authenticated itself using client credentials.

	 username: the accounts username. Used as displayName if no other is set and used when tagging people
            (@username@domain.tld). Usernames can't be changed, but a profile can be moved to a new username
            which will change the username but break all associated statuses, follows, ...
	    email: the initial email address, which will receive the "Confirm Account" email
	 password: the initial password
	agreement: agree or disagree to the locale rules, terms of use and privacy policy
    locale: language of the initial email (ISO6391, i.e. 'en')

Returns a new access token associated with the account, which replaces the previous token

func (*Gotodon) CreateFilter

func (client *Gotodon) CreateFilter(phrase string, context []string, irreversible, wholeWord bool, expiresIn int) (MFilter, error)

Creates a new filter

      phrase: the phrase to be checked for in statuses
     context: the context(s) in which the filter should be applied (one or more of home, notifications, public and/or thread)
irreversible: if true, matching statuses will be dropped from the timeline instead of hidden (only works with context home and notifications) (default: false)
   wholeWord: whether to consider word boundaries when matching (default: false)
   expiresIn: time in seconds when the filter will expire or no-expiration when set to 0 (default: 0)

Returns the newly created filter

func (*Gotodon) CreateList

func (client *Gotodon) CreateList(title string) (MList, error)

Creates a new list

title: title of the new list

Returns the newly created list

func (*Gotodon) CreateSubscription

func (client *Gotodon) CreateSubscription(endpoint, p256dh, auth string, follow, favourite, reblog, mention, poll bool) (MPushSubscription, error)

Creates a new subscription

 endpoint: url of the push endpoint
   p256dh: public key (Base64 encoded string of public key of ECDH key using ‘prime256v1’ curve)
     auth: auth secret (Base64 encoded string of 16 bytes of random data)
   follow: receive follow notifications
favourite: receive favourite notifications
   reblog: receive reblog notifications
  mention: receive mention notifications
     poll: receive poll notifications

Returns the newly created push subscription

func (*Gotodon) DeleteSubscription

func (client *Gotodon) DeleteSubscription() error

Deletes the current subscription

func (*Gotodon) GetAccount

func (client *Gotodon) GetAccount(accountId string) (MAccount, error)

Gets the Account associated with the AccountId.

Returns the account

func (*Gotodon) GetAccountBlocks

func (client *Gotodon) GetAccountBlocks() MAccountBook

Gets a book of accounts the user has blocked.

Returns an AccountBook which can be used to scroll through the pages of blocked accounts.

func (*Gotodon) GetAssociatedAccount

func (client *Gotodon) GetAssociatedAccount() (MAccount, error)

Gets the Account associated with the client.

Returns the account

func (*Gotodon) GetAuthorizeUrl

func (client *Gotodon) GetAuthorizeUrl() string

Returns an url at which a user can grant access to his account which will then return an AuthorizationCode.

The AuthorizationCode can be used by AuthorizeWithAuthorizationCode to get an AccessToken.

func (*Gotodon) GetConversations

func (client *Gotodon) GetConversations() MConversationBook

Gets a book used to scroll through the pages of conversations

limit: only retrieve this amount of statuses per page (default: 40)

Returns a ConversationBook used to scroll through the pages or collect them all at once

func (*Gotodon) GetCustomEmojis

func (client *Gotodon) GetCustomEmojis() ([]gotodonr.Emoji, error)

Get a servers custom emojis

Returns a slice of emojis

func (*Gotodon) GetDomainBlocksBook

func (client *Gotodon) GetDomainBlocksBook() gotodonr.StringBook

Gets a book which can be used to scroll through pages of domains the user has blocked

Returns a StringBook which can be used to scroll through the pages or collect all pages at once

func (*Gotodon) GetEndorsements

func (client *Gotodon) GetEndorsements() MAccountBook

Gets a book which can be used to scroll through pages of accounts the user has endorsed (endorsed accounts are highlighted on the users profile)

Returns an AccountBook which can be used to scroll through the pages or collect all pages at once

func (*Gotodon) GetFavourites

func (client *Gotodon) GetFavourites() MStatusBook

Gets a book which can be used to scroll through pages of statuses favourited by the user

Returns a StatusBook which can be used to scroll through the pages or collect all pages at once

func (*Gotodon) GetFilter

func (client *Gotodon) GetFilter(filterId string) (MFilter, error)

Get a specific filter

filterId: identifier of the filter to be retrieved

Returns the filter for the given id

func (*Gotodon) GetFilters

func (client *Gotodon) GetFilters() ([]MFilter, error)

Get all currently setup filters

Returns a slice of filters

func (*Gotodon) GetFollowRequests

func (client *Gotodon) GetFollowRequests() MAccountBook

Gets a book which can be used to scroll through pages of open follower requests

Returns an AccountBook which can be used to scroll through the pages or collect all pages at once

func (*Gotodon) GetFollowSuggestions

func (client *Gotodon) GetFollowSuggestions() ([]MAccount, error)

Gets all follow suggestions

Returns a slice of suggested accounts

func (*Gotodon) GetHashtagTimeline

func (client *Gotodon) GetHashtagTimeline(hashTag string, local, onlyMedia bool) MStatusBook

Gets a book used to scroll through the pages of statuses in a hashtags timeline

	  hashTag: the hashtag whose timeline to retrieve
     local: only retrieve local statuses (default: false)
	onlyMedia: only retrieve statuses with attachments (default: false)

Returns a StatusBook used to scroll through the pages or collect them all at once

func (*Gotodon) GetHomeTimeline

func (client *Gotodon) GetHomeTimeline() MStatusBook

Gets a book used to scroll through the pages of statuses in the home timeline

Returns a StatusBook used to scroll through the pages or collect them all at once

func (*Gotodon) GetInstance

func (client *Gotodon) GetInstance() (gotodonr.Instance, error)

Gets information about a server

Returns an instance

func (*Gotodon) GetList

func (client *Gotodon) GetList(listId string) (MList, error)

Get a single list created by the user

Returns a list

func (*Gotodon) GetListTimeline

func (client *Gotodon) GetListTimeline(listId string) MStatusBook

Gets a book used to scroll through the pages of statuses in a lists timeline

listId: identifier of the list whose timeline to retrieve

Returns a StatusBook used to scroll through the pages or collect them all at once

func (*Gotodon) GetLists

func (client *Gotodon) GetLists() ([]MList, error)

Get all lists created by the user

Returns a slice of lists

func (*Gotodon) GetMutes

func (client *Gotodon) GetMutes() MAccountBook

Gets a book used to scroll through pages of muted accounts

Returns an AccountBook used to scroll through the pages or collect them all at once

func (*Gotodon) GetNotification

func (client *Gotodon) GetNotification(notificationId string) (MNotification, error)

Get a notification

notificationId: identifier of the notification to get

Returns the notifications

func (*Gotodon) GetNotificationsBook

func (client *Gotodon) GetNotificationsBook(excludeTypes []string, accountId string) MNotificationBook

Gets a book used to scroll through pages of notifications

excludeTypes: types to exclude (one or more of follow, favourite, reblog and/or mention)
   accountId: return notifications which were created due to actions performed by this account (optional)

Returns a NotificationBook used to scroll through the pages or collect all at once

func (*Gotodon) GetPoll

func (client *Gotodon) GetPoll(pollId string) (MPoll, error)

Gets a poll

pollId:  identifier of the poll to get

Returns the poll

func (*Gotodon) GetPublicTimeline

func (client *Gotodon) GetPublicTimeline(local, onlyMedia bool) MStatusBook

Gets a book used to scroll through the pages of statuses in the public timeline

     local: only retrieve local statuses (default: false)
	onlyMedia: only retrieve statuses with attachments (default: false)
	    limit: only retrieve this amount of statuses per page (default: 40)

Returns a StatusBook used to scroll through the pages or collect them all at once

func (*Gotodon) GetRelationships

func (client *Gotodon) GetRelationships(accountIds ...string) ([]MRelationship, error)

Get the relationship to all given accounts

accountIds: Slice of accounts to return

Returns an slice containing a relationship for each given accountId

func (*Gotodon) GetScheduledStatus

func (client *Gotodon) GetScheduledStatus(scheduledId string) (MScheduledStatus, error)

Gets a scheduled status

Returns the scheduled status

func (*Gotodon) GetScheduledStatuses

func (client *Gotodon) GetScheduledStatuses() ([]MScheduledStatus, error)

Get all scheduled statuses

Returns a slice of scheduled statuses

func (*Gotodon) GetStatus

func (client *Gotodon) GetStatus(statusId string) (MStatus, error)

Gets a status

statusId: identifier of the status to get

Returns the status

func (*Gotodon) GetSubscription

func (client *Gotodon) GetSubscription() (MPushSubscription, error)

Gets the current subscription

func (*Gotodon) HasAccountAccess

func (client *Gotodon) HasAccountAccess() (bool, error)

Checks if the client can access account-level functions (functions bound to an account). Account-Level functions also include client-level functions (so if hasAccountAccess is true, it is safe to assume that hasClientAccess is also true).

func (*Gotodon) HasClientAccess

func (client *Gotodon) HasClientAccess() bool

Checks if the client can access client-level functions (functions which are not bound to an account)

func (*Gotodon) IsAuthorized

func (client *Gotodon) IsAuthorized() bool

Checks if the client is authorized (i.e. retrieved an AccessToken)

func (*Gotodon) IsRegistered

func (client *Gotodon) IsRegistered() bool

Checks if the client is registered (i.e. retrieved a ClientId and ClientSecret)

func (*Gotodon) PostMediaStatus

func (client *Gotodon) PostMediaStatus(status, inReplyToId string, mediaIds []string, sensitive bool, spoilerText, visibility, language, idempotencyKey string) (MStatus, error)

Posts a new media status

        status: the text of the status
   inReplyToId: identifier of the status it will reply to (optional)
      mediaIds: identifiers of attachments (media status)
     sensitive: set to true if the post contains sensitive content (default: false)
   spoilerText: text which will be shown instead if the status is marked as sensitive (optional)
    visibility: visibility of the status (either public, private, unlisted or direct) (default: public)
      language: the language of the status (ISO 8601) (optional)
idempotencyKey: helps preventing duplicate posts (optional)

Returns the newly posted status

func (*Gotodon) PostPollStatus

func (client *Gotodon) PostPollStatus(baseUrl, accessToken, status, inReplyToId string, pollOptions []string, pollExpiresIn int, pollMultiple, pollHideTotals, sensitive bool, spoilerText, visibility, language, idempotencyKey string) (MStatus, error)

Posts a new poll

        status: the text of the status
   inReplyToId: identifier of the status it will reply to (optional)
   pollOptions: options for the poll (poll status)
 pollExpiresIn: time in seconds the poll will be live (poll status) (default: DurationDay)
  pollMultiple: set to true to allow multiple choices (poll status) (default: false)
pollHideTotals: set to true to hide the results while the poll is live (poll status) (default: false)
     sensitive: set to true if the post contains sensitive content (default: false)
   spoilerText: text which will be shown instead if the status is marked as sensitive (optional)
    visibility: visibility of the status (either public, private, unlisted or direct) (default: public)
      language: the language of the status (ISO 8601) (optional)
idempotencyKey: helps preventing duplicate posts (optional)

Returns the newly posted status

func (*Gotodon) PostStatus

func (client *Gotodon) PostStatus(status, inReplyToId string, mediaIds []string, pollOptions []string, pollExpiresIn int, pollMultiple, pollHideTotals, sensitive bool, spoilerText, visibility, language, idempotencyKey string) (MStatus, error)

Posts a new status

        status: the text of the status
   inReplyToId: identifier of the status it will reply to (optional)
      mediaIds: identifiers of attachments (media status)
   pollOptions: options for the poll (poll status)
 pollExpiresIn: time in seconds the poll will be live (poll status) (default: DurationDay)
  pollMultiple: set to true to allow multiple choices (poll status) (default: false)
pollHideTotals: set to true to hide the results while the poll is live (poll status) (default: false)
     sensitive: set to true if the post contains sensitive content (default: false)
   spoilerText: text which will be shown instead if the status is marked as sensitive (optional)
    visibility: visibility of the status (either public, private, unlisted or direct) (default: public)
      language: the language of the status (ISO 8601) (optional)
idempotencyKey: helps preventing duplicate posts (optional)

Returns the newly posted status

func (*Gotodon) PostTextStatus

func (client *Gotodon) PostTextStatus(status, inReplyToId string, sensitive bool, spoilerText, visibility, language, idempotencyKey string) (MStatus, error)

Posts a new text status

        status: the text of the status
   inReplyToId: identifier of the status it will reply to (optional)
     sensitive: set to true if the post contains sensitive content (default: false)
   spoilerText: text which will be shown instead if the status is marked as sensitive (optional)
    visibility: visibility of the status (either public, private, unlisted or direct) (default: public)
      language: the language of the status (ISO 8601) (optional)
idempotencyKey: helps preventing duplicate posts (optional)

Returns the newly posted status

func (*Gotodon) Register

func (client *Gotodon) Register(clientname, website string) error

Registers the client as an app

clientName: the name of the application (is shown on statuses)
   website: a website providing more information about your application (optional)

Returns an error (if one occurs)

func (*Gotodon) RevokeAccessToken

func (client *Gotodon) RevokeAccessToken() error

Revoke this clients AccessToken (all authorized calls will fail until the client is authorized again)

func (*Gotodon) ScheduleMediaStatus

func (client *Gotodon) ScheduleMediaStatus(status, scheduledAt, inReplyToId string, mediaIds []string, sensitive bool, spoilerText, visibility, language, idempotencyKey string) (MScheduledStatus, error)

Schedules a new media status

        status: the text of the status
   scheduledAt: timestamp of when the status will be posted
   inReplyToId: identifier of the status it will reply to (optional)
      mediaIds: identifiers of attachments (media status)
     sensitive: set to true if the post contains sensitive content (default: false)
   spoilerText: text which will be shown instead if the status is marked as sensitive (optional)
    visibility: visibility of the status (either public, private, unlisted or direct) (default: public)
      language: the language of the status (ISO 8601) (optional)
idempotencyKey: helps preventing duplicate posts (optional)

Returns the newly scheduled status

func (*Gotodon) SchedulePollStatus

func (client *Gotodon) SchedulePollStatus(status, scheduledAt, inReplyToId string, pollOptions []string, pollExpiresIn int, pollMultiple, pollHideTotals, sensitive bool, spoilerText, visibility, language, idempotencyKey string) (MScheduledStatus, error)

Schedules a new poll

        status: the text of the status
   scheduledAt: timestamp of when the status will be posted
   inReplyToId: identifier of the status it will reply to (optional)
   pollOptions: options for the poll (poll status)
 pollExpiresIn: time in seconds the poll will be live (poll status) (default: DurationDay)
  pollMultiple: set to true to allow multiple choices (poll status) (default: false)
pollHideTotals: set to true to hide the results while the poll is live (poll status) (default: false)
     sensitive: set to true if the post contains sensitive content (default: false)
   spoilerText: text which will be shown instead if the status is marked as sensitive (optional)
    visibility: visibility of the status (either public, private, unlisted or direct) (default: public)
      language: the language of the status (ISO 8601) (optional)
idempotencyKey: helps preventing duplicate posts (optional)

Returns the newly scheduled status

func (*Gotodon) ScheduleStatus

func (client *Gotodon) ScheduleStatus(status, scheduledAt, inReplyToId string, mediaIds []string, pollOptions []string, pollExpiresIn int, pollMultiple, pollHideTotals, sensitive bool, spoilerText, visibility, language, idempotencyKey string) (MScheduledStatus, error)

Schedules a new status

        status: the text of the status
   scheduledAt: timestamp of when the status will be posted
   inReplyToId: identifier of the status it will reply to (optional)
      mediaIds: identifiers of attachments (media status)
   pollOptions: options for the poll (poll status)
 pollExpiresIn: time in seconds the poll will be live (poll status) (default: DurationDay)
  pollMultiple: set to true to allow multiple choices (poll status) (default: false)
pollHideTotals: set to true to hide the results while the poll is live (poll status) (default: false)
     sensitive: set to true if the post contains sensitive content (default: false)
   spoilerText: text which will be shown instead if the status is marked as sensitive (optional)
    visibility: visibility of the status (either public, private, unlisted or direct) (default: public)
      language: the language of the status (ISO 8601) (optional)
idempotencyKey: helps preventing duplicate posts (optional)

Returns the newly scheduled status

func (*Gotodon) ScheduleTextStatus

func (client *Gotodon) ScheduleTextStatus(status, scheduledAt, inReplyToId string, sensitive bool, spoilerText, visibility, language, idempotencyKey string) (MScheduledStatus, error)

Schedules a new text status

        status: the text of the status
   scheduledAt: timestamp of when the status will be posted
   inReplyToId: identifier of the status it will reply to (optional)
     sensitive: set to true if the post contains sensitive content (default: false)
   spoilerText: text which will be shown instead if the status is marked as sensitive (optional)
    visibility: visibility of the status (either public, private, unlisted or direct) (default: public)
      language: the language of the status (ISO 8601) (optional)
idempotencyKey: helps preventing duplicate posts (optional)

Returns the newly scheduled status

func (*Gotodon) Search

func (client *Gotodon) Search(query string, resolve, following bool, limit, offset int) (gotodonr.Result, error)

Search accounts, statuses and tags

query: query to look for
resolve: attempt a WebFinger lookup (default: false)
following: only include accounts the user is following (default: false)
limit: max number of results (default: 40)
offset: result offset of the search (used for pagination) (default: 0)

Returns a result, containing individual slices for accounts, statuses and tags

func (*Gotodon) SearchAccounts

func (client *Gotodon) SearchAccounts(query string, limit int, resolve, following bool) ([]MAccount, error)

Queries all (federated) accounts for the given query (checks username, account and display name)

    query: the string to search for
    limit: maximum number of results per page (default: 40)
  resolve: attempt a webfinger lookup (default: false)
following: limit the search to accounts followed (default: false)

Returns a slice of accounts matching the query

func (*Gotodon) Store

func (client *Gotodon) Store(path string) error

Stores the client at the given path (leave empty to store at client.Filepath)

func (*Gotodon) ToString

func (client *Gotodon) ToString() (error, string)

Serializes the client and returns it as a string

func (*Gotodon) TokenMaintenance

func (client *Gotodon) TokenMaintenance() error

Check if the AccessToken is invalid, and if so, get a new one (only possible when using Login as authorization method)

func (*Gotodon) UnblockDomain

func (client *Gotodon) UnblockDomain(domain string) error

Unblocks the given domain (strip any protocols and such, domain needs to be 'domain.tld')

domain: the domain to be unblocked

func (*Gotodon) UpdateProfile

func (client *Gotodon) UpdateProfile(displayName, biography, locked, privacy, sensitive, language string, fields map[string]string) (MAccount, error)

Updates the account profile with the given values. Values set to "" (empty string) will not be updated, which allows to only update certain values.

displayName: Name shown on a users profile (does not change the username)
  biography: Description shown on a users profile
     locked: if an account is locked, following it will not immediately follow it but rather send a follow request
    privacy: Default privacy for statuses (public, unlisted or private)
  sensitive: Default sensitivity for statuses (true or false)
   language: Default language for posts (ISO6391, i.e. 'en')
     fields: Profile metadata (up to four title/value-pairs shown on a users profile)

Returns the updated account

func (*Gotodon) UpdateProfileAvatar

func (client *Gotodon) UpdateProfileAvatar(path string) (MAccount, error)

Updates the users profile avatar.

path: path to the image which should be uploaded and used as new avatar

Returns the updated account

func (*Gotodon) UpdateProfileHeader

func (client *Gotodon) UpdateProfileHeader(path string) (MAccount, error)

Updates the users profile header.

path: path to the image which should be uploaded and used as new header

Returns the updated account

func (*Gotodon) UpdateSubscription

func (client *Gotodon) UpdateSubscription(follow, favourite, reblog, mention, poll bool) (MPushSubscription, error)

Updates the subscription

   follow: receive follow notifications
favourite: receive favourite notifications
   reblog: receive reblog notifications
  mention: receive mention notifications
     poll: receive poll notifications

Returns the updated push subscription

func (*Gotodon) UploadAndPostMediaStatus

func (client *Gotodon) UploadAndPostMediaStatus(status, inReplyToId string, medias []gotodonr.Media, sensitive bool, spoilerText, visibility, language, idempotencyKey string) (MStatus, error)

Uploads any attachments and posts a new media status

        status: the text of the status
   inReplyToId: identifier of the status it will reply to (optional)
      mediaIds: identifiers of attachments (media status)
     sensitive: set to true if the post contains sensitive content (default: false)
   spoilerText: text which will be shown instead if the status is marked as sensitive (optional)
    visibility: visibility of the status (either public, private, unlisted or direct) (default: public)
      language: the language of the status (ISO 8601) (optional)
idempotencyKey: helps preventing duplicate posts (optional)

Returns the newly posted status

func (*Gotodon) UploadAndScheduleMediaStatus

func (client *Gotodon) UploadAndScheduleMediaStatus(status, scheduledAt, inReplyToId string, medias []gotodonr.Media, sensitive bool, spoilerText, visibility, language, idempotencyKey string) (MScheduledStatus, error)

Uploads any attachments and schedules a new media status

        status: the text of the status
   scheduledAt: timestamp of when the status will be posted
   inReplyToId: identifier of the status it will reply to (optional)
        medias: slice of medias which should be uploaded and attached (optional)
     sensitive: set to true if the post contains sensitive content (default: false)
   spoilerText: text which will be shown instead if the status is marked as sensitive (optional)
    visibility: visibility of the status (either public, private, unlisted or direct) (default: public)
      language: the language of the status (ISO 8601) (optional)
idempotencyKey: helps preventing duplicate posts (optional)

Returns the newly scheduled status

func (*Gotodon) UploadMedia

func (client *Gotodon) UploadMedia(filePath, description string, focusX, focusY float64) (MAttachment, error)

Uploads a new media object which can be used as attachment

   filePath: path to the file which should be uploaded
description: description of the file (for screen readers and loading errors) (optional, max 420 characters))
     focusX: x-axis focal point, between 0.0 and 1.0 (default: 0.0)
     focusY: y-axis focal point, between 0.0 and 1.0 (default: 0.0)

Returns the newly created attachment

func (*Gotodon) VerifyAccessToken

func (client *Gotodon) VerifyAccessToken() error

Verifies that the AccessToken is at least a valid client token (contrary to an access token associated with an account). AccessTokens that are valid can be used to authorize the client but unless they were received using an authorization method, they can't be used to post statuses, update a profile or use other methods that require an account.

See tootsuite/mastodon/app/controllers/api/v1/apps/credentials_controller.rb: https://github.com/tootsuite/mastodon/blob/master/app/controllers/api/v1/apps/credentials_controller.rb

func (*Gotodon) VerifyAccountCredentials

func (client *Gotodon) VerifyAccountCredentials() (MAccount, error)

Verifies that the AccessToken is a valid token and associated with an account (tokens generated by authenticating using client credentials are not associated with an account and can't be used for account calls, like posting statuses, liking, reblogging, ...)

type Login

type Login struct {
	Email    string `json:"email"`
	Password string `json:"password"`
}

Set of credentials used to login

type MAccount

type MAccount struct {
	gotodonr.Account
}

An account of a user, with profile data and statistics

func (*MAccount) AuthorizeFollowRequest

func (account *MAccount) AuthorizeFollowRequest(client *Gotodon) error

Accepts a follower request

accountId: identifier of the account whose follow request should be accepted

func (*MAccount) BlockAccount

func (account *MAccount) BlockAccount(client *Gotodon) (MRelationship, error)

Blocks the account.

Returns the updated relationship

func (*MAccount) DeleteFollowSuggestion

func (account *MAccount) DeleteFollowSuggestion(client *Gotodon) error

Deletes a follow suggestion

func (*MAccount) Endorse

func (account *MAccount) Endorse(client *Gotodon) (gotodonr.Relationship, error)

Endorses (pins) the account

Returns the updated relationship

func (*MAccount) Follow

func (account *MAccount) Follow(client *Gotodon, hideReblogs string) (MRelationship, error)

Follow the account.

hideReblogs:  show/hide reblogs in timelines and such (default: false)

Returns the new relationship

func (*MAccount) GetFolloweds

func (account *MAccount) GetFolloweds(client *Gotodon) MAccountBook

Gets a book which can be used to scroll through pages of accounts followed by the account

accountId: id of the account the followeds should be retrieved from
    limit: maximum amount of accounts to retrieve per page (default: 40)

Returns an AccountBook which can be used to scroll through the pages or collect all pages at once

Note that when account points to a local account, all followed accounts will be retrieved. If it points to a remote (federated) account, only local accounts will be retrieved.

func (*MAccount) GetFollowers

func (account *MAccount) GetFollowers(client *Gotodon) MAccountBook

Gets a book which can be used to scroll through pages of followers

Returns an AccountBook which can be used to scroll through the pages or collect all pages at once

Note that when account points to a local account, all followers will be retrieved. If it points to a remote (federated) account, only local accounts will be retrieved.

func (*MAccount) GetLists

func (account *MAccount) GetLists(client *Gotodon) ([]MList, error)

Get all lists containing an account

Returns a slice of lists containing the account

func (*MAccount) GetStatuses

func (account *MAccount) GetStatuses(client *Gotodon, onlyMedia, onlyPinned, excludeReplies, excludeReblogs bool) MStatusBook

Gets a book which can be used to scroll through pages of statuses (visible to the user) posted by the account.

     onlyMedia: only retrieve statuses which include media (default: false)
    onlyPinned: only retrieve statuses which are pinned (default: false)
excludeReplies: exclude statuses which reply to other statuses (default: false)
excludeReblogs: exclude reblogs (default: false)
         limit: only retrieve this amount of statuses per page (default: 40)

Returns an StatusBook which can be used to scroll through the pages or collect all pages at once

Note that when accountId points to a local account, all statuses will be retrieved. If it points to a remote (federated) account, only statuses posted after it first appeared to the server will be retrieved.

func (*MAccount) Mute

func (account *MAccount) Mute(client *Gotodon, notifications bool) (gotodonr.Relationship, error)

Mutes the account

notifications: if notifications for this account should be muted as well (default: true)

Returns the updated relationship

func (*MAccount) RejectFollowRequest

func (account *MAccount) RejectFollowRequest(client *Gotodon) error

Rejects a follower request

accountId: identifier of the account whose follow request should be rejected

func (*MAccount) Report

func (account *MAccount) Report(client *Gotodon, statusIds []string, comment string, forward bool) error

Reports a user

statusIds: statuses which show violations of the ToS (optional)
  comment: additional information on why the user is being reported (optional, up to 1000 characters)
  forward: forward the report to the accounts server if it isn't the local server (default: false)

func (*MAccount) UnblockAccount

func (account *MAccount) UnblockAccount(client *Gotodon) (MRelationship, error)

Unblocks the account

Returns the updated relationship

func (*MAccount) Unendorse

func (account *MAccount) Unendorse(client *Gotodon) (gotodonr.Relationship, error)

Unendorses (unpins) the account

Returns the updated relationship

func (*MAccount) Unfollow

func (account *MAccount) Unfollow(client *Gotodon) (MRelationship, error)

Unfollow the account.

Returns the new relationship

func (*MAccount) Unmute

func (account *MAccount) Unmute(client *Gotodon) (gotodonr.Relationship, error)

Unmutes the account

Returns the updated relationship

type MAccountBook

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

Book used to scroll through accounts

func NewManagedAccountBook

func NewManagedAccountBook(accountBook gotodonr.AccountBook) MAccountBook

Creates a new ManagedAccountBook

func (*MAccountBook) All

func (book *MAccountBook) All() []MAccount

Returns all available accounts. Warning: Can take a long time (receives a maximum of 80 accounts per second)

func (*MAccountBook) Current

func (book *MAccountBook) Current() []MAccount

Returns the values from the current page

func (*MAccountBook) Next

func (book *MAccountBook) Next() []MAccount

Updates the book to the values from the next page

func (*MAccountBook) Previous

func (book *MAccountBook) Previous() []MAccount

Updates the book to the values from the previous page

type MAlerts

type MAlerts struct {
	gotodonr.Alerts
}

Set of alerts which a subscription can be subscribed to TODO: Should be booleans, but server returns JSON strings

type MApp

type MApp struct {
	gotodonr.App
}

The app retrieved when registering a client at a mastodon server

type MApplication

type MApplication struct {
	gotodonr.Application
}

Display data of the application used to post a status

type MAttachment

type MAttachment struct {
	gotodonr.Attachment
}

Data of an attachment which can be added to a status

func (*MAttachment) UpdateMedia

func (attachment *MAttachment) UpdateMedia(client *Gotodon, description string, focusX, focusY float64) (MAttachment, error)

Updates an existing attachment

description: description of the file (for screen readers and loading errors) (optional, max 420 characters))
     focusX: x-axis focal point, between 0.0 and 1.0 (default: 0.0)
     focusY: y-axis focal point, between 0.0 and 1.0 (default: 0.0)

Returns the updated attachment

type MCard

type MCard struct {
	gotodonr.Card
}

Card data used to generate a preview/embedding for links in statuses

type MContext

type MContext struct {
	gotodonr.Context
}

The context of a status, used in conversations

type MConversation

type MConversation struct {
	gotodonr.Conversation
}

Data of a conversation

type MConversationBook

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

Book used to scroll through accounts

func NewManagedConversationBook

func NewManagedConversationBook(conversationBook gotodonr.ConversationBook) MConversationBook

Creates a new ManagedConversationBook

func (*MConversationBook) All

func (book *MConversationBook) All() []MConversation

Returns all available accounts. Warning: Can take a long time (receives a maximum of 80 accounts per second)

func (*MConversationBook) Current

func (book *MConversationBook) Current() []MConversation

Returns the values from the current page

func (*MConversationBook) Next

func (book *MConversationBook) Next() []MConversation

Updates the book to the values from the next page

func (*MConversationBook) Previous

func (book *MConversationBook) Previous() []MConversation

Updates the book to the values from the previous page

type MEmoji

type MEmoji struct {
	gotodonr.Emoji
}

Data used for custom emojis

type MError

type MError struct {
	gotodonr.Error
}

Data sent by the server to provide information why an action/request failed

type MField

type MField struct {
	gotodonr.Field
}

A field shown on a users profile (up to four fields can be set)

type MFilter

type MFilter struct {
	gotodonr.Filter
}

Data for a filter used to automatically hide statuses from users

func (*MFilter) DeleteFilter

func (filter *MFilter) DeleteFilter(client *Gotodon) error

Removes a filter

func (*MFilter) UpdateFilter

func (filter *MFilter) UpdateFilter(client *Gotodon, filterId, phrase string, context []string, irreversible, wholeWord bool, expiresIn int) (MFilter, error)

Updates an existing filter

      phrase: the phrase to be checked for in statuses
     context: the context(s) in which the filter should be applied (one or more of home, notifications, public and/or thread)
irreversible: if true, matching statuses will be dropped from the timeline instead of hidden (only works with context home and notifications) (default: false)
   wholeWord: whether to consider word boundaries when matching (default: false)
   expiresIn: time in seconds when the filter will expire or no-expiration when set to 0 (default: 0)

Returns the updated filter

type MFocus

type MFocus struct {
	gotodonr.Focus
}

Focus data of an image, used to align the preview image

type MHistory

type MHistory struct {
	gotodonr.History
}

A dated statistic of the uses for a (hash) tag

type MInstance

type MInstance struct {
	gotodonr.Instance
}

Data used to provide information about a mastodon server

type MList

type MList struct {
	gotodonr.List
}

Lists allow the creation of timelines which only contains statuses by a specified set of accounts

func (*MList) AddAccounts

func (list *MList) AddAccounts(client *Gotodon, accounts ...string) error

Adds the accounts to the list

accounts: slice of accounts which should be added to the list

func (*MList) DeleteList

func (list *MList) DeleteList(client *Gotodon) error

Deletes the list

listId: identifier of the list to be updated

func (*MList) GetAccounts

func (list *MList) GetAccounts(client *Gotodon) MAccountBook

Gets a book used to scroll through the pages of accounts in a list

Returns an AccountBook used to scroll through the pages or collect all at once

func (*MList) RemoveAccounts

func (list *MList) RemoveAccounts(client *Gotodon, accounts ...string) error

Removes the accounts from the list

accounts: slice of accounts which should be removed from the list

func (*MList) Update

func (list *MList) Update(client *Gotodon, title string) (MList, error)

Updates a list

title: the new title of the list

Returns the updated list

type MMedia

type MMedia struct {
	gotodonr.Media
}

A struct used when uploading media attachments within the status post call

type MMention

type MMention struct {
	gotodonr.Mention
}

Data of a mentioned account

type MMeta

type MMeta struct {
	gotodonr.Meta
}

Metadata of an attachment

type MMetaAttributes

type MMetaAttributes struct {
	gotodonr.MetaAttributes
}

Metadata of an attachment

type MNotification

type MNotification struct {
	gotodonr.Notification
}

Data of a notification

func (*MNotification) Dismiss

func (notification *MNotification) Dismiss(client *Gotodon) error

Dismisses the notification

Returns the notifications

type MNotificationBook

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

Book used to scroll through accounts

func NewManagedNotificationBook

func NewManagedNotificationBook(notificationBook gotodonr.NotificationBook) MNotificationBook

Creates a new ManagedNotificationBook

func (*MNotificationBook) All

func (book *MNotificationBook) All() []MNotification

Returns all available accounts. Warning: Can take a long time (receives a maximum of 80 accounts per second)

func (*MNotificationBook) Current

func (book *MNotificationBook) Current() []MNotification

Returns the values from the current page

func (*MNotificationBook) Next

func (book *MNotificationBook) Next() []MNotification

Updates the book to the values from the next page

func (*MNotificationBook) Previous

func (book *MNotificationBook) Previous() []MNotification

Updates the book to the values from the previous page

type MPoll

type MPoll struct {
	gotodonr.Poll
}

Data of a poll

func (*MPoll) Vote

func (poll *MPoll) Vote(client *Gotodon, choices ...int) (MPoll, error)

Posts a vote on the poll

choices: one (or more) ordinals of choices to vote on (multiple ordinals can only be used when the vote allows multiple choices)

Returns the updated poll

type MPollOption

type MPollOption struct {
	gotodonr.PollOption
}

Data for a single choice in a poll

type MPushSubscription

type MPushSubscription struct {
	gotodonr.PushSubscription
}

Data for the push subscription

type MRelationship

type MRelationship struct {
	gotodonr.Relationship
}

Relationship data between two accounts

type MResult

type MResult struct {
	gotodonr.Result
}

Set of search results

type MScheduledStatus

type MScheduledStatus struct {
	gotodonr.ScheduledStatus
}

Data of a scheduled status

func (*MScheduledStatus) Delete

func (status *MScheduledStatus) Delete(client *Gotodon) error

Deletes a scheduled status

func (*MScheduledStatus) Update

func (status *MScheduledStatus) Update(client *Gotodon, scheduledAt string) (MScheduledStatus, error)

Moves a scheduled status to a new time

scheduledAt: timestamp of when the status should be scheduled

Returns the updated scheduled status

type MSource

type MSource struct {
	gotodonr.Source
}

Source data of an account

type MStats

type MStats struct {
	gotodonr.Stats
}

Statistics for a mastodon server

type MStatus

type MStatus struct {
	gotodonr.Status
}

Data of a status

func (*MStatus) Delete

func (status *MStatus) Delete(client *Gotodon) error

Deletes the status

func (*MStatus) Favourite

func (status *MStatus) Favourite(client *Gotodon) (MStatus, error)

Favourites the status

Returns the status

func (*MStatus) GetCard

func (status *MStatus) GetCard(client *Gotodon) (gotodonr.Card, error)

Gets the card of the status

Returns the card

func (*MStatus) GetContext

func (status *MStatus) GetContext(client *Gotodon) (gotodonr.Context, error)

Gets the context of the status

Returns the context

func (*MStatus) GetFavouritedBy

func (status *MStatus) GetFavouritedBy(client *Gotodon) MAccountBook

Gets a book used to scroll through the pages of accounts which favourited the status

Returns an AccountBook which can be used to scroll through the pages or collect all at once

func (*MStatus) GetRebloggedBy

func (status *MStatus) GetRebloggedBy(client *Gotodon) MAccountBook

Gets a book used to scroll through the pages of accounts which reblogged the status

Returns an AccountBook which can be used to scroll through the pages or collect all at once

func (*MStatus) Mute

func (status *MStatus) Mute(client *Gotodon) (MStatus, error)

Mutes the status

Returns the status

func (*MStatus) Pin

func (status *MStatus) Pin(client *Gotodon) (MStatus, error)

Pins the status

func (*MStatus) Reblog

func (status *MStatus) Reblog(client *Gotodon) (MStatus, error)

Reblogs the status

func (*MStatus) Unfavourite

func (status *MStatus) Unfavourite(client *Gotodon) (MStatus, error)

Unfavourites the status

statusId: identifier of the status which should be unfavourited

Returns the status

func (*MStatus) Unmute

func (status *MStatus) Unmute(client *Gotodon) (MStatus, error)

Unmutes the status

Returns the status

func (*MStatus) Unpin

func (status *MStatus) Unpin(client *Gotodon) (MStatus, error)

Unpins the status

func (*MStatus) Unreblog

func (status *MStatus) Unreblog(client *Gotodon) (MStatus, error)

Unreblogs the status

type MStatusBook

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

Book used to scroll through accounts

func NewManagedStatusBook

func NewManagedStatusBook(statusBook gotodonr.StatusBook) MStatusBook

Creates a new ManagedStatusBook

func (*MStatusBook) All

func (book *MStatusBook) All() []MStatus

Returns all available accounts. Warning: Can take a long time (receives a maximum of 80 accounts per second)

func (*MStatusBook) Current

func (book *MStatusBook) Current() []MStatus

Returns the values from the current page

func (*MStatusBook) Next

func (book *MStatusBook) Next() []MStatus

Updates the book to the values from the next page

func (*MStatusBook) Previous

func (book *MStatusBook) Previous() []MStatus

Updates the book to the values from the previous page

type MStatusParams

type MStatusParams struct {
	gotodonr.StatusParams
}

Data of a status that is yet to be posted

type MTag

type MTag struct {
	gotodonr.Tag
}

Data of a (hash) tag

type MToken

type MToken struct {
	gotodonr.Token
}

Token data retrieved when authorizing a client

type MURLs

type MURLs struct {
	gotodonr.URLs
}

Data pointing to a endpoint which can be used by WebSockets

Jump to

Keyboard shortcuts

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