view release on metacpan or  search on metacpan

README.md  view on Meta::CPAN

# NAME

Mastodon::Client - Talk to a Mastodon server

# SYNOPSIS

    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](https://metacpan.org/pod/HTTP::Thin). It is expected to have a `request` method that
    accepts [HTTP::Request](https://metacpan.org/pod/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](https://metacpan.org/pod/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**

README.md  view on Meta::CPAN

    - **media\_ids**

        An array reference of up to four media IDs. These can be obtained as the result
        of a call to **upload\_media()**.

    - **sensitive**

        Boolean, to mark 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 the value of `coerce_entities`, it returns the new
    Mastodon::Entity::Status object, or a plain hash reference.

- **delete\_status($id)**

    Delete a status by ID. The ID is mandatory. Returns an empty object.

- **reblog($id)**
- **unreblog($id)**
- **favourite($id)**
- **unfavourite($id)**

    Reblog or favourite a status by ID, or revert this action. The ID argument is
    mandatory.

    Depending on the value of `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 defines 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.

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

    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 the value of `coerce_entities`, it returns an array of
    Mastodon::Entity::Status objects, or a plain array reference. The more recent
    statuses come first.

# STREAMING RESULTS

Alternatively, it is possible to use the streaming API to get a constant stream
of updates. To do this, there is the **stream()** method.

- **stream($query)**

    Creates a Mastodon::Listener object which will fetch a stream for the
    specified query. Possible values for the query are either `user`, for events
    that are relevant to the authorized user; `public`, for all public statuses;
    or a tag (if it begins with the `#` character), for all public statuses for
    the particular tag.

    For more details on how to use this object, see the documentation for
    [Mastodon::Listener](https://metacpan.org/pod/Mastodon::Listener).

    Accessing streaming public timeline does not require authentication.

# REQUEST METHODS

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

They all take a URL as their first parameter, which can be a string with the
API endpoint to contact, or a [URI](https://metacpan.org/pod/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.

- **delete($url)**
- **get($url)**
- **get($url, $params)**

    Query parameters can be passed as part of the [URI](https://metacpan.org/pod/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](https://metacpan.org/pod/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.

- **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.

# CONTRIBUTIONS AND BUG REPORTS

Contributions of any kind are most welcome!

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.

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.

# 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.