Mastodon-Client

 view release on metacpan or  search on metacpan

README.md  view on Meta::CPAN

      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.

README.md  view on Meta::CPAN

        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.

examples/listener  view on Meta::CPAN

use strict;
use warnings;
use open ':std', ':encoding(UTF-8)';

use Mastodon::Listener;

my $access_token = shift
    or die "You must pass an access token as the first argument\n";

my $listener = Mastodon::Listener->new(
    url => 'https://botsin.space/api/v1/streaming/public',
    access_token => $ARGV[0],
    coerce_entities => 1,
);

$listener->on( error => sub {
    my ( undef, undef, $msg ) = @_;
    warn $msg;
});

$listener->on( update => sub {

lib/Mastodon/Client.pm  view on Meta::CPAN

sub stream {
  my $self = shift;

  state $check = compile( NonEmptyStr );
  my ($query) = $check->(@_);

  my $endpoint
    = $self->instance->uri
    . '/api/v'
    . $self->api_version
    . '/streaming/'
    . (( $query =~ /^#/ )
        ? ( 'hashtag?' . $query )
        : $query
      );

  use Mastodon::Listener;
  return Mastodon::Listener->new(
    url             => $endpoint,
    access_token    => $self->access_token,
    coerce_entities => $self->coerce_entities,

lib/Mastodon/Client.pm  view on Meta::CPAN

    my ($listener, $status) = @_;
    printf "%s said: %s\n",
      $status->account->display_name,
      $status->content;
  });
  $listener->start;

=head1 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
(B<post>, B<get>, etc), which allow direct access to the API endpoints. All
other methods call one of these at some point.

lib/Mastodon/Client.pm  view on Meta::CPAN

=back

Depending on the value of C<coerce_entities>, it returns an array of
Mastodon::Entity::Status objects, or a plain array reference. The more recent
statuses come first.

=back

=head1 STREAMING RESULTS

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

=over 4

=item B<stream($query)>

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

For more details on how to use this object, see the documentation for
L<Mastodon::Listener>.

Accessing streaming public timeline does not require authentication.

=back

=head1 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.

lib/Mastodon/Listener.pm  view on Meta::CPAN

  isa => Int,
  default => 1,
);

has url => (
  is => 'ro',
  lazy => 1,
  default => sub {
      $_[0]->instance
    . '/api/v' . $_[0]->api_version
    . '/streaming/' . $_[0]->stream;
  },
);

has stream => (
  is => 'ro',
  lazy => 1,
  default => 'public',
);

has access_token => (

lib/Mastodon/Listener.pm  view on Meta::CPAN

};

1;

__END__

=encoding utf8

=head1 NAME

Mastodon::Listener - Access the streaming API of a Mastodon server

=head1 SYNOPSIS

  # From Mastodon::Client
  my $listener = $client->stream( 'public' );

  # Or use it directly
  my $listener = Mastodon::Listener->new(
    url => 'https://mastodon.cloud/api/v1/streaming/public',
    access_token => $token,
    coerce_entities => 1,
  )

  $listener->on( update => sub {
    my ($listener, $status) = @_;
    printf "%s said: %s\n",
      $status->account->display_name,
      $status->content;
  });

lib/Mastodon/Listener.pm  view on Meta::CPAN

The B<stop> method can be called from within callbacks to disconnect from the
stream.

=head1 ATTRIBUTES

=over 4

=item B<access_token>

The OAuth2 access token of your application, if authorization is needed. This
is not needed for streaming from public timelines.

=item B<api_version>

The API version to use. Defaults to C<1>.

=item B<coerce_entities>

Whether JSON responses should be coerced into Mastodon::Entity objects.
Currently defaults to false (but this will likely change in v0.01).

lib/Mastodon/Listener.pm  view on Meta::CPAN

from a URL, and defaults to C<mastodon.social>.

=item B<stream>

The stream to use. Current valid streams are C<public>, C<user>, and tag
timelines. To access a tag timeline, the argument to this value should begin
with a hash character (C<#>).

=item B<url>

The full streaming URL to use. By default, it is constructed from the values in
the B<instance>, B<api_version>, and B<stream> attributes.

=back

=head1 EVENTS

=over 4

=item B<update>