Class: MastoApi

MastoApi(api, user)

Singleton class for interacting with the authenticated Mastodon API for the user's home server. Handles caching, concurrency, and provides methods for fetching and updating Mastodon data.

Constructor

new MastoApi(api, user)

Private constructor for MastoApi. Instantiate with `MastoApi.init()`.
Parameters:
Name Type Description
api mastodon.rest.Client Mastodon REST API client.
user Account The authenticated user account.
Properties:
Name Type Attributes Description
api mastodon.rest.Client The Mastodon REST API client instance.
apiErrors Array.<Error> Array of errors encountered while using the API.
homeDomain string The Fedialgo user's home server domain.
logger Logger API logger instance.
user Account The Fedialgo user's Account object.
userData UserData <optional>
 The Fedialgo user's historical info.
waitTimes Record.<CacheKey, WaitTime> Tracks the amount of time spent waiting for each endpoint's API responses.

Members

(static) instance

Returns the singleton instance of MastoApi.

Methods

accountUrl(tag) → {string}

Returns the URL for an account on the Feialgo user's home server.
Parameters:
Name Type Description
tag MastodonTag | string The tag or tag object.
Returns:
The tag URL.
Type
string

currentState() → {Record.<string, (object|string)>}

Get the value of some MastoApi object's properties. For debugging/presentation only.
Returns:
Type
Record.<string, (object|string)>

(async) fetchHomeFeed(params) → {Promise.<Array.<Toot>>}

Fetches the user's home timeline feed (recent toots from followed accounts and hashtags).
Parameters:
Name Type Description
params HomeTimelineParams Parameters for fetching the home feed.
Returns:
Array of Toots in the home feed.
Type
Promise.<Array.<Toot>>

fillInDefaultParams(params) → {FetchParamsWithDefaults.<T>}

Populates fetch options with basic defaults for API requests.
Parameters:
Name Type Description
params FetchParams.<T> Fetch parameters.
Returns:
Fetch parameters with defaults filled in.
Type
FetchParamsWithDefaults.<T>

(async) getBlockedAccounts() → {Promise.<Array.<Account>>}

Gets the accounts blocked by the user (does not include muted accounts).
Returns:
Array of blocked accounts.
Type
Promise.<Array.<Account>>

(async) getBlockedDomains() → {Promise.<Array.<string>>}

Gets the Mastodon server domains that the user has blocked Safe domain for testing: https://universeodon.com/@memes@pl.m0e.space
Returns:
Set of blocked domains.
Type
Promise.<Array.<string>>

(async) getCacheableToots(fetchStatuses, cacheKey, maxRecords) → {Promise.<Array.<Toot>>}

Generic data getter for cacheable Toots with custom fetch logic. Used for various hashtag feeds (participated, trending, favourited).
Parameters:
Name Type Description
fetchStatuses function Function to fetch statuses.
cacheKey ApiCacheKey Cache key for storage.
maxRecords number Maximum number of records to fetch.
Returns:
Array of Toots.
Type
Promise.<Array.<Toot>>

(async) getFavouritedToots(paramsopt) → {Promise.<Array.<Toot>>}

Gets the toots recently favourited by the user.
Parameters:
Name Type Attributes Description
params ApiParams <optional>
 Optional parameters.
Returns:
Array of favourited Toots.
Type
Promise.<Array.<Toot>>

(async) getFollowedAccounts(paramsopt) → {Promise.<Array.<Account>>}

Gets the accounts followed by the user.
Parameters:
Name Type Attributes Description
params ApiParams <optional>
 Optional parameters.
Returns:
Array of followed accounts.
Type
Promise.<Array.<Account>>

(async) getFollowedTags(paramsopt) → {Promise.<Array.<mastodon.v1.Tag>>}

Gets the hashtags followed by the user.
Parameters:
Name Type Attributes Description
params ApiParams <optional>
 Optional parameters.
Returns:
Array of followed tags.
Type
Promise.<Array.<mastodon.v1.Tag>>

(async) getFollowers(paramsopt) → {Promise.<Array.<Account>>}

Gets the followers of the Fedialgo user.
Parameters:
Name Type Attributes Description
params ApiParams <optional>
 Optional parameters.
Returns:
Array of follower accounts.
Type
Promise.<Array.<Account>>

(async) getHomeserverTimelineToots(params) → {Promise.<Array.<Toot>>}

Get the public toots on the user's home server (recent toots from users on the same server).
Parameters:
Name Type Description
params ApiParams
Returns:
Array of public toots from the home server.
Type
Promise.<Array.<Toot>>

(async) getMutedAccounts(paramsopt) → {Promise.<Array.<Account>>}

Gets all muted accounts (including fully blocked accounts).
Parameters:
Name Type Attributes Description
params ApiParams <optional>
 Optional parameters.
Returns:
Array of muted and blocked accounts.
Type
Promise.<Array.<Account>>

(async) getNotifications(paramsopt) → {Promise.<Array.<mastodon.v1.Notification>>}

Gets the user's recent notifications.
Parameters:
Name Type Attributes Description
params ApiParamsWithMaxID <optional>
 Optional parameters.
Returns:
Array of notifications.
Type
Promise.<Array.<mastodon.v1.Notification>>

(async) getRecentUserToots(paramsopt) → {Promise.<Array.<Toot>>}

Gets the user's recent toots.
Parameters:
Name Type Attributes Description
params ApiParamsWithMaxID <optional>
 Optional parameters.
Returns:
Array of recent user Toots.
Type
Promise.<Array.<Toot>>

(async) getServerSideFilters() → {Promise.<Array.<mastodon.v2.Filter>>}

Retrieves content-based feed filters set up by the user on the server.
Returns:
Array of server-side filters.
Type
Promise.<Array.<mastodon.v2.Filter>>

(async) getStatusesForTag(tagName, logger, numTootsopt) → {Promise.<Array.<TootLike>>}

Gets the latest toots for a given tag using both the Search API and tag timeline API. The two APIs give results with surprisingly little overlap (~80% of toots are unique).
Parameters:
Name Type Attributes Description
tagName string The tag to search for.
logger Logger Logger instance for logging.
numToots number <optional>
 Number of toots to fetch.
Returns:
Array of TootLike objects.
Type
Promise.<Array.<TootLike>>

(async) getUserData(forceopt) → {Promise.<UserData>}

Retrieves background data about the user for scoring, etc. Caches as an instance variable.
Parameters:
Name Type Attributes Description
force boolean <optional>
 If true, forces a refresh from the API.
Returns:
The UserData object.
Type
Promise.<UserData>

(async) hashtagTimelineToots(tagName, logger, maxRecordsopt) → {Promise.<Array.<Toot>>}

Fetches toots from the tag timeline API (different from the search API). Concurrency is managed by a semaphore. See https://docs.joinmastodon.org/methods/v1/timelines/#tag TODO: Could maybe use min_id and max_id to avoid re-fetching the same data
Parameters:
Name Type Attributes Description
tagName string The tag to fetch toots for.
logger Logger Logger instance for logging.
maxRecords number <optional>
 Maximum number of records to fetch.
Returns:
Array of Toots.
Type
Promise.<Array.<Toot>>

(async) instanceInfo() → {Promise.<mastodon.v2.Instance>}

Retrieves the user's home instance (mastodon server) configuration from the API.
Returns:
The instance configuration.
Type
Promise.<mastodon.v2.Instance>

isLocalUrl(url) → {boolean}

Returns true if the URL is a local URL on the Feialgo user's home server.
Parameters:
Name Type Description
url string URL to check
Returns:
Type
boolean

(async) lockAllMutexes() → {Promise.<Array.<ConcurrencyLockRelease>>}

Locks all API and cache mutexes for cache state operations.
Returns:
Array of lock release functions.
Type
Promise.<Array.<ConcurrencyLockRelease>>

loggerForParams(params) → {Logger}

Returns a logger instance for the given fetch parameters.
Parameters:
Name Type Description
params Omit.<FetchParams.<T>, "fetch"> Fetch parameters (excluding fetch).
Returns:
Logger instance.
Type
Logger

reset()

Resets the API state, clearing errors and user data, and resetting concurrency.

(async) resolveToot(toot) → {Promise.<Toot>}

Resolves a foreign server toot URI to one on the user's local server using the v2 search API. transforms URLs like this: https://fosstodon.org/@kate/114360290341300577 to this: https://universeodon.com/@kate@fosstodon.org/114360290578867339
Parameters:
Name Type Description
toot Toot The toot to resolve.
Returns:
The resolved toot.
Type
Promise.<Toot>

(async) searchForToots(searchStr, logger, maxRecordsopt) → {Promise.<Array.<mastodon.v1.Status>>}

Performs a keyword substring search for toots using the search API.
Parameters:
Name Type Attributes Description
searchStr string The string to search for.
logger Logger Logger instance for logging.
maxRecords number <optional>
 Maximum number of records to fetch.
Returns:
Array of status objects.
Type
Promise.<Array.<mastodon.v1.Status>>

setSemaphoreConcurrency(concurrency)

Sets the concurrency for the request semaphore.
Parameters:
Name Type Description
concurrency number The new concurrency value.

tagUrl(tag) → {string}

Returns the URL for a tag on the Feialgo user's home server.
Parameters:
Name Type Description
tag MastodonTag | string The tag or tag object.
Returns:
The tag URL.
Type
string

(async, static) init(api, user) → {Promise.<void>}

Initializes the singleton MastoApi instance with the provided Mastodon API client and user account. If an instance already exists, logs a warning and does nothing. Loads user data from storage and assigns it to the instance.
Parameters:
Name Type Description
api mastodon.rest.Client The Mastodon REST API client.
user Account The authenticated user account.
Returns:
Resolves when initialization is complete.
Type
Promise.<void>

(static) throwIfAccessTokenRevoked(logger, error, msg)

Throws if the error is an access token revoked error, otherwise logs and moves on.
Parameters:
Name Type Description
logger Logger Logger instance.
error unknown The error to check.
msg string Message to log.
Throws:
If the error is an access token revoked error.
Type
unknown

(static) throwSanitizedRateLimitError(error, msg)

Throws a sanitized rate limit error if detected, otherwise logs and throws the original error.
Parameters:
Name Type Description
error unknown The error to check.
msg string Message to log.
Throws:
Throws a user-friendly rate limit warning or the original error.
Type
string | unknown