NAME

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

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;
         });

         $listener->start;

DESCRIPTION

       A Mastodon::Listener object is created by calling the stream method from a
       Mastodon::Client, and it exists for the sole purpose of parsing a stream of events from a
       Mastodon server.

       Mastodon::Listener objects inherit from Role::EventEmitter. Please refer to its
       documentation for details on how to register callbacks for the different events.

       Once callbacks have been registered, the listener can be set in motion by calling its
       start method, which takes no arguments and never returns.  The stop method can be called
       from within callbacks to disconnect from the stream.

ATTRIBUTES

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

       api_version
           The API version to use. Defaults to 1.

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

       instance
           The instance to use, as a Mastodon::Entity::Instance object. Will be coerced from a
           URL, and defaults to "mastodon.social".

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

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

EVENTS

       update
           A new status has appeared. Callback will be called with the listener and the new
           status.

       notification
           A new notification has appeared. Callback will be called with the listener and the new
           notification.

       delete
           A status has been deleted. Callback will be called with the listener and the ID of the
           deleted status.

       heartbeat
           A new ":thump" has been received from the server. This is mostly for debugging
           purposes.

       error
           Inherited from Role::EventEmitter, will be emitted when an error was found.  The
           callback will be called with a fatal flag, an error message, and any relevant data as
           a single third arghument.

           If the error event is triggered in response to a 4xx or 5xx error, the data payload
           will be an array reference with the response and request objects as received from
           Net::Async::HTTP.

AUTHOR

       •   José Joaquín Atria <jjatria@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.