File Coverage

blib/lib/WebService/Gitter.pm

Criterion	Covered	Total	%
statement	12	147	8.1
branch	0	124	0.0
condition	0	21	0.0
subroutine	4	23	17.3
pod	19	19	100.0
total	35	334	10.4

package WebService::Gitter;
$WebService::Gitter::VERSION = '2.2.0';
#ABSTRACT: An interface to Gitter REST API via Perl 5.

use strict;
use warnings;

use Moo;
use Function::Parameters;
with 'WebService::Client';

has api_key => (
    is       => 'ro',
    required => 1
);

has '+base_url' => ( default => 'https://api.gitter.im/v1' );

method get_me() {

    return $self->get( "/user/me?access_token=" . $self->api_key );
}

method list_groups() {

    return $self->get( "/groups?access_token=" . $self->api_key );
}

method rooms_under_group($group_id) {

    return $self->get(
        "/groups/$group_id/rooms?access_token=" . $self->api_key );
}

method rooms( : $q = '' ) {
    return $self->get( "/rooms?access_token=" . $self->api_key . "&q=$q" );
}

method room_from_uri( : $uri ) {
    return $self->post( "/rooms?access_token=" . $self->api_key,
        { uri => $uri } );
}

method join_room( $room_id, $user_id ) {
    return $self->post( "/user/$user_id/rooms?access_token=" . $self->api_key,
        { id => $room_id } );
}

method remove_user_from_room( $room_id, $user_id ) {
    return $self->delete(
        "/rooms/$room_id/users/$user_id?access_token=" . $self->api_key );
}

method update_room( $room_id,
    : $topic   = '',
    : $noindex = 'false',
    : $tags    = '' )
{
    return $self->put(
        "/rooms/$room_id?access_token=" . $self->api_key,
        { topic => $topic, noindex => $noindex, tags => $tags }
    );
}

method delete_room($room_id) {
    return $self->delete( "/rooms/$room_id?access_token=" . $self->api_key );
}

method room_users( $room_id, : $q = '', : $skip = 0, : $limit = 30 ) {
    return $self->get( "/rooms/$room_id/users?access_token="
          . $self->api_key
          . "&skip=$skip"
          . "&limit=$limit" )
      if not $q;

    return $self->get( "/rooms/$room_id/users?access_token="
          . $self->api_key . "&q=$q"
          . "&skip=$skip"
          . "&limit=$limit" )
      if $q;
}

method list_messages(
      $room_id,
    : $skip     = 0,
    : $beforeId = '',
    : $afterId  = '',
    : $aroundId = '',
    : $limit    = 30,
    : $q        = ''
  )
{
    return $self->get( "/rooms/$room_id/chatMessages?access_token="
          . $self->api_key
          . "&skip=$skip"
          . "&beforeId=$beforeId"
          . "&afterId=$afterId"
          . "&aroundId=$aroundId"
          . "&limit=$limit"
          . "&q=$q" );
}

method single_message( $room_id, $message_id ) {
    return $self->get( "/rooms/$room_id/chatMessages/$message_id"
          . "?access_token="
          . $self->api_key );
}

method send_message( $room_id, : $text ) {
    return $self->post(
        "/rooms/$room_id/chatMessages?access_token=" . $self->api_key,
        { text => $text } );
}

method update_message( $room_id, $message_id, : $text ) {
    return $self->put(
        "/rooms/$room_id/chatMessages/$message_id?access_token="
          . $self->api_key,
        { text => $text }
    );
}

method unread_items( $user_id, $room_id ) {
    return $self->get(
        "/user/$user_id/rooms/$room_id/unreadItems?access_token="
          . $self->api_key );
}

method mark_unread_items( $user_id, $room_id, @chat_ids ) {
    return $self->post(
        "/user/$user_id/rooms/$room_id/unreadItems?access_token="
          . $self->api_key,
        { chat => @chat_ids }
    );
}

method orgs($user_id) {
    return $self->get( "/user/$user_id/orgs?access_token=" . $self->api_key );
}

method repos($user_id) {
    return $self->get( "/user/$user_id/repos?access_token=" . $self->api_key );
}

method channels($user_id) {
    return $self->get(
        "/user/$user_id/channels?access_token=" . $self->api_key );
}

1;

=pod

=encoding UTF-8

=head1 NAME

WebService::Gitter - An interface to Gitter REST API via Perl 5.

=head1 VERSION

version 2.2.0

=head1 SYNOPSIS

    use strict;
    use warnings;
    use WebService::Gitter;

    my $git = WebService::Gitter->new(api_key => 'secret');

    # Get current authenticated user.
    $git->get_me;

    # List groups belonging to the authenticated user.
    $git->list_groups;

    # List all rooms belonging to the group/community.
    $git->rooms_under_group($group_id);

    # List all rooms belonging to the searched user.
    $git->rooms(q => $query);

    # List room data via URI.
    $git->room_from_uri(uri => $room_uri);

    # Join a room.
    $git->join_room($room_id, $user_id);

    # Leave/remove user from a room.
    $git->remove_user_from_room($room_id, $user_id);

    # Update room.
    $git->update_room($room_id, topic => $topic, noindex => $noindex, tags => $tags);

    # Delete room.
    $git->delete_room($room_id);

    # List all users in a room.
    $git->room_users($room_id, q => $query, skip => $skip_n, limit => $limit_n);

    # List all messages in a room.
    $git->list_messages($room_id, skip => $skip_n, beforeId => $beforeId,
    afterId => $afterId, aroundId => $aroundId, limit => $limit_n,
    q => $query);

    # Get single message in a room using its message ID.
    $git->single_message($room_id, $message_id);

    # Send message/text to a room.
    $git->send_message($room_id, text => $text);

    # Update message/text in a room.
    $git->update_message($room_id, $message_id, text => $new_text);

    # Retrieve unread items and mentions from a room.
    $git->unread_items($user_id, $room_id);

    # Use to mark chat messages as read.
    $git->mark_unread_items($user_id, $room_id, @chat_ids);

    # List of the user's GitHub Repositories and their respective Room if available.
    $git->orgs($user_id);

    # List of the user's GitHub Repositories and their respective Room if available.
    $git->repos($user_id);

    # List of Gitter channels nested under the current user.
    $git->channels($user_id);

=begin html












=end html

=head1 NOTE

This module does not support Faye endpoint and streaming API..yet. Currently as of writing this, the Gitter's API is
 still in beta and likely to break backward compatibility in the future.

=head2 Methods

=over 4

=item C 'your_api_key')>

Description: Set Pixabay API key.

=item C

Description: Get current authenticated user.

Returns: Authenticated user data.

=item C

Description: List joined groups by the authenticated user.

Returns: Authenticated user joined groups data.

=item C

Description: List all rooms belonging to the group/community.

Parameter: B C<$group_id> - Group/community ID.

Returns: All rooms data belonging to the particular community.

=item C $query)>

Description: List all rooms belonging to the searched user.

Parameter: B C<$query> - Search/query string.

Returns: All rooms data belonging to the user.

=item C $room_uri)>

Description: List room data via URI.

Parameter: B C<$room_uri> - Room URI.

Returns: Room from URI response message.

=item C

Description: Join a room.

Parameter: B C<$room_id> - Room ID.

Parameter: B C<$user_id> - User ID.

Returns: Join room message response.

=item C

Description: Remove a user from a room.
This can be self-inflicted to leave the the room and remove room from your left menu.

Parameter: B C<$room_id> - Room ID.

Parameter: B C<$user_id> - User ID.

Returns: Remove user from a room response message.

=item C $topic, noindex =E $noindex, tags =E $tags)>

Description: Update room.

Parameter: B C<$room_id> - Room ID.

Parameter: B C<$topic> - Room topic.

Parameter: B C<$noindex> - (false, true) Whether the room is indexed by search engines.

Parameter: B C<$tags> - 'tag1, tag2, etc' Tags that define the room.

Returns: Update room response message.

=item C

Description: Delete room.

Parameter: B C<$room_id> - Room ID.

Returns: Delete room response message.

=item C $query, skip =E $skip_n, limit =E $limit_n)>

Description: List all users in a room.

Note: By default, it will skip 0 and return only 30 users data.

Parameter: B C<$room_id> - Room ID.

Parameter: B C<$query> - User's search/query string.

Parameter: B C<$skip_n> - Skip n users.

Parameter: B C<$limit_n> - Set return limit.

Returns: All users data belonging to the room.

=item C $skip_n, beforeId =E $beforeId,
afterId =E $afterId, aroundId =E $aroundId, limit =E $limit_n,
q =E $query)>

Description: List all messages in a room.

Note: By default, it will skip 0 and return only 30 users data.

Parameter: B C<$room_id> - Room ID.

Parameter: B C<$skip_n> - Skip n messages (constrained to 5000 or less).

Parameter: B C<$beforeId> - Get messages before beforeId.

Parameter: B C<$afterId> - Get messages after afterId.

Parameter: B C<$aroundId> - Get messages after aroundId.

Parameter: B C<$limit_n> - Maximum number of messages to return (constrained to 100 or less).

Parameter: B C<$query> - Search query.

Returns: List of messages in a room.

=item C

Description: Get single message in a room using its message ID.

Parameter: B C<$room_id> - Room ID.

Parameter: B C<$message_id> - Message ID.

Returns: Retrieve a single message using its ID.

=item C $text)>

Description: Send message/text to a room.

Parameter: B C<$room_id> - Room ID.

Parameter: B C<$text> - Text to send.

Returns: Retrieve send message response.

=item C $new_text)>

Description: Update message/text in a room.

Parameter: B C<$room_id> - Room ID.

Parameter: B C<$message_id> - Message ID.

Parameter: B C<$new_text> - Text to replace old message.

Returns: Retrieve update message response.

=item C

Description: Retrieve unread items and mentions from a room.

Parameter: B C<$user_id> - User ID.

Parameter: B C<$room_id> - Room ID.

Returns: Unread items response.

=item C

Description: Mark chat messages as read.

Parameter: B C<$user_id> - User ID.

Parameter: B C<$room_id> - Room ID.

Parameter: B C<@chat_ids> - List of chat ids to mark as read.

Returns: Marked chat_ids/items response.

=item C

Description: List of the user's GitHub Repositories and their respective Room if available.

B: It'll return private repositories if the current user has granted Gitter privileges to access them.

Parameter: B C<$user_id> - User ID.

Returns: User's organizations response.

=item C

Description: List of the user's GitHub Repositories and their respective Room if available.

B: It'll return private repositories if the current user has granted Gitter privileges to access them.

Parameter: B C<$user_id> - User ID.

Returns: User's repositories list data response.

=item C

Description: List of Gitter channels nested under the current user.

Parameter: B C<$user_id> - User ID.

Returns: User's channel list response.

=back

=head1 SEE ALSO

L

L

L

=head1 AUTHOR

faraco

=head1 COPYRIGHT AND LICENSE

This software is Copyright (c) 2017-2018 by faraco.

This is free software, licensed under:

  The MIT (X11) License

=cut

__END__