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.