Elefan

A client library implementing the full v1 REST API protocol for Mastodon, in Guile.

Installation

I should make up a Makefile or add this to Guix, at some point, but, for now, you'll just have to handle this manually, I'm afraid.

This is a super simple and plain set of modules so you can just simply copy the elefan directory to /usr/share/guile/<version>/ or wherever your setup of Guile loads modules.

Then, you can just load the specific modules you want to make use of.

Usage

Modules

I've attempted to break out the various functions into sections to make it easier to use and load exactly what you want so modules are broken out around subject.

So you don't have to manually load multiple modules, each module #:re-exports the elements that might be used in conjunction with the subject.

For example, the API's JSON status objects have an account property which holds the JSON account object representation of whomever made the account. As such, (elefan statuses) #:re-exports all the functions and records related to Masto accounts so you don't have to remember to use the necessary additional module, if you decide you want to do anything with that property.

The available modules are (with links to their documentation):

• (elefan auth)
• (elefan accounts)
• (elefan blocks)
• (elefan domain-blocks)
• (elefan emojis)
• (elefan endorsements)
• (elefan favorites)
• (elefan filters)
• (elefan follow-requests)
• (elefan follow-suggestions)
• (elefan instances)
• (elefan lists)
• (elefan media-attachments)
• (elefan mutes)
• (elefan notifications)
• (elefan polls)
• (elefan reports)
• (elefan scheduled-statuses)
• (elefan search)
• (elefan statuses)
• (elefan timelines)

Simple Example

Unless using an API endpoint which doesn't require some level of authorization (e.g. masto-emojis-on-instance), you will need to initialize an app. for a particular instance with masto-app-instantiate.

These functions live in the (elefan auth) module so make sure to include in your file

(use-modules (elefan auth))

To generate a new client for the instance you want to authorize with, simply run

(masto-app-instantiate "https://mastodon.social")

(or with the instance URL you'd prefer).

This will default to using a scope of read unless you specify otherwise.

For example, you could specify more than just read like

(masto-app-instantiate "https://mastodon.social" #:scopes '("read" "write" "follow" "push"))

This will, then, generate a client for you on mastodon.social.

If you've already created a client on an instance, you can pass along #:id, #:secret, and #:key to reuse your client.

While that generates your <mastodon-instance-application> record, calling masto-app-token on it will result in #f since we haven't gotten a token – with it –, yet.

This can be accomplished via three different functions:

• masto-app-set-token-via-client-cred!
• masto-app-set-token-via-code!
• masto-app-set-token-via-user-cred!

If you're, for example, just going to authorize with user credentials, you could just do

(masto-app-set-token-via-user-cred! instantiatedApp "E-mail" "password")

This will return the app. you gave it but, also, set! the token on the app. so you don't have to save the result, if you don't want to.

And that's it.

You can then use that app. to pass it to any other functions which require authorization. For example, you could check out all of the conversations of the user by simply doing

(masto-conversations-all instantiatedAppWithToken)