🐘 Universal Mastodon API client for JavaScript
Recent social media trends have transformed Mastodon's environment. Specifically, tighter API restrictions and the ending of automated accounts on other platforms highlight the need for a similar library in the Fediverse.
This release contains several updates necessary to more easily develop Mastodon clients and bot accounts.
// Pre v6
const masto = await login({
url: "https://example.com",
accessToken: "TOKEN"
})
// v6
const rest = createRestAPIClient({
url: "https://example.com",
accessToken: "TOKEN"
})
const ws = createStreamingAPIClient({
streamingApiUrl: "wss://example.com",
accessToken: "TOKEN"
})
The functions for creating clients have been changed to synchronous functions, and separate functions are now provided for the Streaming API and the REST API.
// Pre v6
masto.v1.accounts.follow("123");
masto.v2.media.update("123", { description: "description"});
masto.v1.timelines.listHashtag("mastodon");
// v6
masto.v1.accounts.$select("123").follow()
masto.v2.media.$select("123").update({ description: "description"});
masto.v1.timelines.hashtag.$select("mastodon").list();
Prior to v6, Masto.js had inconsistent property names indicating endpoints, with some endpoints using one word and others using two word method names. Also, endpoints whose path contained the ID of an entity received this as an argument, and the correspondence with the URL was ambiguous.
In v6, property names have been significantly revamped to provide a more consistent API for each endpoint. Basically, for the API /api/foo/bar/baz, an API foo.bar.baz is provided, with slashes replaced by dots.
Also, for endpoints that include path as an ID, a method $select is provided instead of taking the ID as an argument. This clarifies naming conventions and reduces bundle size.
The HTTP methods GET, POST, PATCH, and DELETE are supported as before with methods fetch, create, update, and remove. The list method is provided for endpoints that support pagination. As an exception, endpoints whose path ends with a verb (/follow, /add) will use that verb regardless of the HTTP method.
// Pre v6
const connect = () => {
const stream = masto.streamPublic();
stream.on("update", (event) => {
...
});
stream.ws.on("close", () => {
connect();
});
}
connect();
// v6
for await (const entry of masto.public.subscribe()) {
...
}
Prior to v6, Masto.js provided a streaming API using EventEmitter, which has been revamped to an API using Async Iterator. For more information on the benefits of Async Iterator, see this article.
In addition, to avoid overloading the Mastodon instances, we have changed to use multiplexed connections. This allows all subscriptions to share one WebSocket connection.
In addition, starting with v6, we have added the ability to automatically reconnect using exponential backoff in the event of a WebSocket connection error. This makes it easier to develop bot accounts and other applications that require real-time response.
EventStream
setDirection and getDirection to paginator (2ad2da7)retry option (4b06ae1)