Mastodon::Client(3pm)

Mastodon::Client(3pm) 💅

User Contributed Perl Documentation but make it main character energy. bestie, this is the module that lets you talk to a Mastodon server, and it's lowkey iconic.

---

✨ NAME ✨

Mastodon::Client — Talk to a Mastodon server. That's it. That's the vibe. 💖

🌸 SYNOPSIS 🌸

okay so here's the quickstart, fr fr:

         use Mastodon::Client;

         my $client = Mastodon::Client->new(
           instance        => 'mastodon.social',
           name            => 'PerlBot',
           client_id       => $client_id,
           client_secret   => $client_secret,
           access_token    => $access_token,
           coerce_entities => 1,
         );

         $client->post_status('Posted to a Mastodon server!');
         $client->post_status('And now in secret...',
           { visibility => 'unlisted' }
         )

         # Streaming interface might change!
         my $listener = $client->stream( 'public' );
         $listener->on( update => sub {
           my ($listener, $status) = @_;
           printf "%s said: %s\n",
             $status->account->display_name,
             $status->content;
         });
         $listener->start;

🦋 DESCRIPTION 🦋

Mastodon::Client lets you talk to a Mastodon server to obtain authentication credentials, read posts from timelines in both static or streaming mode, and perform all the other operations exposed by the Mastodon API.

Most of these are available through the convenience methods listed below, which validate input parameters and are likely to provide more meaningful feedback in case of errors.

Alternatively, this distribution can be used via the low-level request methods (post, get, etc), which allow direct access to the API endpoints. All other methods call one of these at some point.

⚠️ VERSION NOTICE ⚠️

This distribution currently only supports version 1 of the Mastodon API.

Help implementing support for any missing features in version 1, and for the new features in version 2, would be greatfully appreciated.

👑 ATTRIBUTES 👑

• instance — A Mastodon::Entity::Instance object representing the instance to which this client will speak. Defaults to "mastodon.social".
• api_version — An integer specifying the version of the API endpoints to use. Defaults to 1.
• redirect_uri — The URI to which authorization codes should be forwarded as part of the OAuth2 flow. Defaults to "urn:ietf:wg:oauth:2.0:oob" (meaning no redirection).
• user_agent — The user agent to use for the requests. Defaults to an instance of HTTP::Thin. It is expected to have a "request" method that accepts HTTP::Request objects.
• coerce_entities — A boolean value. Set to true if you want Mastodon::Client to internally coerce all response entities to objects. This adds a level of validation, and can make the objects easier to use. Although this does require some additional processing, the coercion is done by Type::Tiny, so the impact is negligible. For now, it defaults to false (but this will likely change, so I recommend you use it).
• access_token — The access token of your client. This is provided by the Mastodon API and is used for the OAuth2 authentication required for most API calls. You can get this by calling authorize with either an access code or your account's username and password.
• authorized — Boolean. False is the client has no defined access_token. When an access token is set, this is set to true or to a DateTime object representing the time of authorization if possible (as received from the server).
• client_id, client_secret — The client ID and secret are provided by the Mastodon API when you register your client using the register method. They are used to identify where your calls are coming from, and are required before you can use the authorize method to get the access token.
• name — Your client's name. This is required when registering, but is otherwise seldom used. If you are using the authorization_url to get an access code from your users, then they will see this name when they go to that page.
• account — Holds the authenticated account. It is set internally by the get_account method.
• scopes — This array reference holds the scopes set by you for the client. These are required when registering your client with the Mastodon instance. Defaults to "read". Mastodon::Client will internally make sure that the scopes you were provided when calling authorize match those that you requested. If this is not the case, it will helpfully die.
• website — The URL of a human-readable website for the client. If made available, it appears as a link in the "authorized applications" tab of the user preferences in the default Mastodon web GUI. Defaults to the empty string.

💅 METHODS 💅

💌 Authorizing an application 💌

Although not all of the API methods require authentication to be used, most of them do. The authentication process involves a) registering an application with a Mastodon server to obtain a client secret and ID; b) authorizing the application by either providing a user's credentials, or by using an authentication URL.

The methods facilitating this process are detailed below:

🌟 register() / register(%data) 🌟

Obtain a client secret and ID from a given mastodon instance. Takes a single hash as an argument, with the following possible keys:

• redirect_uris — The URL to which authorization codes should be forwarded after authorized by the user. Defaults to the value of the redirect_uri attribute.
• scopes — The scopes requested by this client. Defaults to the value of the scopes attribute.
• website — The client's website. Defaults to the value of the "website" attribute.

When successful, sets the "client_secret", "scopes", and "client_id" attributes of the Mastodon::Client object and returns the modified object.

This should be called once per client and its contents cached locally.

🌈 authorization_url() 🌈

Generate an authorization URL for the given application. Accessing this URL via a browser by a logged in user will allow that user to grant this application access to the requested scopes. The scopes used are the ones in the scopes attribute at the time this method is called.

🎀 authorize() / authorize( %data ) 🎀

Grant the application access to the requested scopes for a given user. This method takes a hash with either an access code or a user's login credentials to grant authorization. Valid keys are:

• access_code — The access code obtained by visiting the URL generated by authorization_url.
• username, password — The user's login credentials.

When successful, the method automatically sets the client's authorized attribute to a true value and caches the access_token for all future calls.

😭 Error handling 😭

Methods that make requests to the server will die whenever an error is encountered, or the data that was received from the server is not what is expected. The error string will, when possible, come from the response's status line, but this will likely not be enough to fully diagnose what went wrong.

💀 latest_response 💀

To make this easier, the client will cache the server's response after each request has been made, and expose it through the "latest_response" accessor.

Note that, as its name implies, this will only store the most recent response.

If called before any request has been made, it will return an undefined value.

The remaining methods listed here follow the order of those in the official API documentation.

👥 Accounts 👥

🫶 get_account() / get_account($id) / get_account($params) / get_account($id, $params) 🫶

Fetches an account by ID. If no ID is provided, this defaults to the current authenticated account. Global GET parameters are available for this method.

Depending on the value of "coerce_entities", it returns a Mastodon::Entity::Account object, or a plain hash reference.

✨ update_account($params) ✨

Make changes to the authenticated account. Takes a hash reference with the following possible keys:

• display_name, note — Strings
• avatar, header — A base64 encoded image, or the name of a file to be encoded.

Depending on the value of "coerce_entities", returns the modified Mastodon::Entity::Account object, or a plain hash reference.

🦋 followers() / followers($id) / followers($params) / followers($id, $params) 🦋

Get the list of followers of an account by ID. If no ID is provided, the one for the current authenticated account is used. Global GET parameters are available for this method.

Depending on the value of "coerce_entities", returns an array reference of Mastodon::Entity::Account objects, or a plain array reference.

🌸 following() / following($id) / following($params) / following($id, $params) 🌸

Get the list of accounts followed by the account specified by ID. If no ID is provided, the one for the current authenticated account is used. Global GET parameters are available for this method.

Depending on the value of "coerce_entities", returns an array reference of Mastodon::Entity::Account objects, or a plain array reference.

💜 statuses() / statuses($id) / statuses($params) / statuses($id, $params) 💜

Get a list of statuses from the account specified by ID. If no ID is provided, the one for the current authenticated account is used.

In addition to the global GET parameters, this method accepts the following parameters:

• only_media
• exclude_replies Both boolean.

Depending on the value of "coerce_entities", returns an array reference of Mastodon::Entity::Status objects, or a plain array reference.

🍓 follow($id) / unfollow($id) 🍓

Follow or unfollow an account specified by ID. The ID argument is mandatory.

Depending on the value of "coerce_entities", returns the new Mastodon::Entity::Relationship object, or a plain hash reference.

🔥 block($id) / unblock($id) 🔥

Block or unblock an account specified by ID. The ID argument is mandatory.

Depending on the value of "coerce_entities", returns the new Mastodon::Entity::Relationship object, or a plain hash reference.

🧚 mute($id) / unmute($id) 🧚

Mute or unmute an account specified by ID. The ID argument is mandatory.

Depending on the value of "coerce_entities", returns the new Mastodon::Entity::Relationship object, or a plain hash reference.

relationships(@ids)

relationships(@ids, $params)

okay so this one pulls the tea ☕ on how the currently authenticated user relates to a bunch of accounts you name by ID. You need at least one ID (mandatory bestie, no skipping), but you can throw in as many as you want at once — the more the merrier fr fr. Global GET parameters are on the table here, and you pass them as an extra hash reference tacked on as the final argument.

Depending on whatever coerce_entities is set to, you get back either an array reference of Mastodon::Entity::Relationship objects, or just a plain array reference. ✨

search_accounts($query)

search_accounts($query, $params)

Hunting for accounts 🔍 — takes a mandatory string to use as the search query. Cute lil plot twist: if your query looks like "username@domain", the accounts get searched remotely instead of locally.

On top of the global GET parameters, this one also takes:

• limit — the max number of matches you want. Defaults to 40.

Depending on coerce_entities, you get an array reference of Mastodon::Entity::Account objects, or a plain array reference.

🫶 This method does not require authentication. No login, no problem.

---

🌈 Blocks

blocks()

blocks($params)

Gets the list of accounts the authenticated user has blocked 🚫. Global GET parameters work here.

Depending on coerce_entities, it hands you an array reference of Mastodon::Entity::Account objects, or a plain array reference.

💖 Favourites

favourites()

favourites($params)

Gets the list of statuses the authenticated user has favourited ⭐. Global GET parameters are available.

Depending on coerce_entities, you get an array reference of Mastodon::Entity::Status objects, or a plain array reference.

🦋 Follow requests

follow_requests()

follow_requests($params)

Gets the list of accounts asking to follow the authenticated user 👀. Global GET parameters are available for this one.

Depending on coerce_entities, it returns an array reference of Mastodon::Entity::Account objects, or a plain array reference.

authorize_follow($id)

reject_follow($id)

Accept or reject the follow request from the account with the specified ID — the ID argument is mandatory, no vibes-based guessing.

Returns an empty object. That's it, that's the whole thing 💅

🌸 Follows

remote_follow($acct)

Follow a remote user by their account string (ie. "username@domain"). The argument is mandatory.

Depending on coerce_entities, it returns a Mastodon::Entity::Account object, or a plain hash reference holding the local representation of the account you named.

🧚 Instances

fetch_instance()

Fetches the freshest info about the current instance the client is talking to ✨. When it works, this method updates the value of the instance attribute — so yes, it's got side effects, it's giving main character.

Depending on coerce_entities, it returns a Mastodon::Entity::Instance object, or a plain hash reference.

🫶 This method does not require authentication.

🎀 Media

upload_media($file)

upload_media($file, $params)

Uploads a file as an attachment 📎. Takes a mandatory argument naming a local file to encode and upload, plus an optional hash reference with these extra goodies:

• description — a plain-text description of the media, for accessibility, as a string.
• focus — an array reference of two floating point values, used as the x and y focus values. These tell clients which point in the image is the most important one to show in a cropped view.

The value of a coordinate is a real number between -1 and +1, where 0 is the center. x:-1 indicates the left edge of the image, x:1 the right edge. For the y axis, y:1 is the top edge and y:-1 is the bottom.

Depending on coerce_entities, it returns a Mastodon::Entity::Attachment object, or a plain hash reference.

The returned object's ID can be passed to post_status to post it to a timeline 🔥

💜 Mutes

mutes()

mutes($params)

Gets the list of accounts the authenticated user has muted 🤫. Global GET parameters are available.

Depending on coerce_entities, it returns an array reference of Mastodon::Entity::Account objects, or a plain array reference.

⭐ Notifications

notifications()

notifications($params)

Gets the list of notifications for the authenticated user 🔔. Global GET parameters are available.

Depending on coerce_entities, you get an array reference of Mastodon::Entity::Notification objects, or a plain array reference.

get_notification($id)

Gets a single notification by ID. The argument is mandatory, bestie.

Depending on coerce_entities, it returns a Mastodon::Entity::Notification object, or a plain hash reference.

clear_notifications()

Clears all notifications for the authenticated user. Clean slate energy ✨

This method takes no arguments and returns an empty object.

🍓 Reports

reports()

reports($params)

Gets a list of reports made by the authenticated user 📝. Global GET parameters are available.

Depending on coerce_entities, it returns an array reference of Mastodon::Entity::Report objects, or a plain array reference.

report($params)

Report a user or a status. Takes a mandatory hash with these keys:

• account_id — the ID of a single account to report.
• status_ids — the ID of a single status to report, or an array reference of statuses to report.
• comment — an optional string.

While the comment is always optional, either the account_id or the list of status_ids must be present. One of them, bestie, or it's not happening 🙈

Depending on coerce_entities, it returns the new Mastodon::Entity::Report object, or a plain hash reference.

🔍 Search

search($query)

search($query, $params)

Searches for content. Takes a mandatory string argument to use as the search query. If the query is a URL, Mastodon will attempt to fetch the account or status it points to 🌐. Otherwise, it does a local account and hashtag search.

On top of the global GET parameters, this method also takes:

• resolve — whether to resolve non-local accounts.

👑

🌈 Statuses

get_status($id)

get_status($id, $params)

Fetches a status by ID. The ID argument is mandatory. Global GET parameters are available here as an additional hash reference.

Depending on coerce_entities, it returns a Mastodon::Entity::Status object, or a plain hash reference.

🫶 This method does not require authentication.

get_status_context($id)

get_status_context($id, $params)

Fetches the context of a status by ID. The ID argument is mandatory. Global GET parameters are available as an additional hash reference.

Depending on coerce_entities, it returns a Mastodon::Entity::Context object, or a plain hash reference.

🫶 This method does not require authentication.

get_status_card($id)

get_status_card($id, $params)

Fetches a card associated with a status by ID 🃏. The ID argument is mandatory. Global GET parameters are available as an additional hash reference.

Depending on coerce_entities, it returns a Mastodon::Entity::Card object, or a plain hash reference.

🫶 This method does not require authentication.

get_status_reblogs($id)

get_status_reblogs($id, $params)

get_status_favourites($id)

get_status_favourites($id, $params)

Fetches a list of accounts who have reblogged or favourited a status by ID. The ID argument is mandatory. Global GET parameters are available as an additional hash reference.

Depending on coerce_entities, it returns an array reference of Mastodon::Entity::Account objects, or a plain array reference.

🫶 This method does not require authentication.

post_status($text)

post_status($text, $params)

Posts a brand new status 🎉. Takes a mandatory string as the content of the status (which, fun fact, can be the empty string), plus an optional hash reference with these extra params:

• status — the content of the status, as a string. Since it's already given as the first argument of the method, this isn't necessary. But if you do provide it, this value will overwrite the first argument's value.
• in_reply_to_id — the optional ID of a status to reply to.
• media_ids — an array reference of up to four media IDs. Grab these as the result of a call to upload_media().
• sensitive — boolean, to mark the status content as NSFW.
• spoiler_text — a string, to be shown as a warning before the actual content.
• visibility — a string; one of "direct", "private", "unlisted", or "public".

Depending on coerce_entities, it returns the new Mastodon::Entity::Status object, or a plain hash reference.

delete_status($id)

Deletes a status by ID. The ID is mandatory. Returns an empty object. Gone, deleted, not coming back 💀

reblog($id)

unreblog($id)

favourite($id)

unfavourite($id)

Reblog or favourite a status by ID, or undo that action 🔁. The ID argument is mandatory.

Depending on coerce_entities, it returns the specified Mastodon::Entity::Status object, or a plain hash reference.

🌈 Timelines

timeline($query)

timeline($query, $params)

Retrieves a timeline 🕰️. The first argument says either the name of a timeline (which can be one of "home" or "public"), or a hashtag (if it begins with the "#" character). This argument is mandatory.

On top of the global GET parameters, this method also takes:

Accessing the public and tag timelines does not require authentication. 🫶

• local — boolean. If true, limits results only to those originating from the current instance. Only applies to public and tag timelines.

Depending on coerce_entities, it returns an array of Mastodon::Entity::Status objects, or a plain array reference. And heads up bestie — the more recent statuses come first ✨

🌊 STREAMING RESULTS 🌊

okay so alternatively, bestie, if you want a constant stream of updates instead of like, asking over and over? there's the streaming API. and for that there's the stream() method. live feed energy fr fr 💖

stream($query)

Creates a Mastodon::Listener object that will fetch a stream for whatever query you passed. Possible values for the query are:

• "user" — for events that are relevant to the authorized user (that's you, main character 👑)
• "public" — for all public statuses
• a tag — if it begins with the "#" character, you get all public statuses for that particular tag 🎀

For more deets on how to actually use this object, go read the documentation for Mastodon::Listener. she's got her own page, slay.

✨ Accessing the streaming public timeline does not require authentication. no login, no gatekeeping, we love to see it 💅

---

📡 REQUEST METHODS 📡

Mastodon::Client uses four lower-level request methods to contact the API with GET, POST, PATCH, and DELETE requests. They're left available in case one of the higher-level convenience methods is unsuitable or undesirable — but you use them at your own risk. no cap. 🙈

They all take a URL as their first parameter, which can be:

• a string with the API endpoint to contact, or
• a URI object, which will be used as-is.

If passed as a string, the methods expect one that contains only the variable parts of the endpoint (ie. not including the "HOST/api/v1" part). The remaining parts will be filled-in appropriately internally. she does the boring bits for you 💖

delete($url)

get($url)

get($url, $params)

Query parameters can be passed as part of the URI object, but it is not recommended you do so, since Mastodon has expectations for array parameters that do not meet those of eg. URI::QueryParam. It will be easier and safer if any additional parameters are passed as a hash reference, which will be added to the URL before the request is sent. trust. 🫶

post($url)

post($url, $data)

patch($url)

patch($url, $data)

the "post" and "patch" methods work similarly to "get" and "delete", but the optional hash reference is sent in as form data, instead of processed as query parameters. The Mastodon API does not use query parameters on POST or PATCH endpoints. that's just how it is bestie 💅

---

🐛 CONTRIBUTIONS AND BUG REPORTS 🐛

Contributions of any kind are most welcome! like genuinely, come hang out 🎀

The main repository for this distribution is on GitLab <https://gitlab.com/jjatria/Mastodon-Client>, which is where patches and bug reports are mainly tracked. The repository is also mirrored on Github <https://github.com/jjatria/Mastodon-Client>, in case that platform makes it easier to post contributions. pick your fave, both are valid ✨

If none of the above is acceptable, bug reports can also be sent through the CPAN RT system, or by mail directly to the developers at the address below, although these will not be as closely tracked. lowkey a vibe but highkey slower 💀

---

👑 AUTHOR 👑

• José Joaquín Atria <jjatria@cpan.org>

---

🦋 CONTRIBUTORS 🦋

• Lance Wicks <lancew@cpan.org>

---

📜 COPYRIGHT AND LICENSE 📜

This software is copyright (c) 2017 by José Joaquín Atria.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. 🌈

---

and that's a wrap on the whole page bestie!! 🎀 this was Mastodon::Client, documented for perl v5.36.0, dated 2022-11-03 — go forth and post, you absolute icon 💖✨👑