Mattermost.pm 4.8 KB
Newer Older
1
package WebService::Mattermost;
Mike Jones's avatar
Mike Jones committed
2

3
use Moo;
Mike Jones's avatar
Mike Jones committed
4 5 6
use Types::Standard qw(Bool Int Object Str);

use WebService::Mattermost::V4::API;
7

8
our $VERSION = 0.005;
Mike Jones's avatar
Mike Jones committed
9

10
with 'WebService::Mattermost::Role::Logger';
11 12 13

################################################################################

Mike Jones's avatar
Mike Jones committed
14 15 16
has [ qw(base_url username password) ] => (is => 'ro', isa => Str, required => 1);

has api_version                => (is => 'ro', isa => Int,  default => 4);
17
has [ qw(authenticate debug) ] => (is => 'rw', isa => Bool, default => 0);
Mike Jones's avatar
Mike Jones committed
18 19 20 21 22 23
has [ qw(auth_token user_id) ] => (is => 'rw', isa => Str,  default => '');

has api => (is => 'ro', isa => Object, lazy => 1, builder => 1);

################################################################################

24 25 26
sub BUILD {
    my $self = shift;

Mike Jones's avatar
Mike Jones committed
27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48
    unless ($self->auth_token) {
        $self->_try_authentication();
    }

    return 1;
}

################################################################################

sub _try_authentication {
    my $self = shift;

    if ($self->authenticate && $self->username && $self->password) {
        # Log into Mattermost at runtime. The entire API requires an auth token
        # which is sent back from the login method.
        my $ret = $self->api->users->login($self->username, $self->password);

        if ($ret->is_success) {
            $self->auth_token($ret->headers->header('Token'));
            $self->user_id($ret->content->{id});
            $self->_set_resource_auth_token();
        } else {
49
            $self->logger->fatal($ret->message);
Mike Jones's avatar
Mike Jones committed
50 51 52 53 54 55
        }
    } elsif ($self->authenticate && !($self->username && $self->password)) {
        $self->logger->logdie('"username" and "password" are required attributes for authentication');
    } elsif ($self->auth_token) {
        $self->_set_resource_auth_token();
    }
Mike Jones's avatar
Mike Jones committed
56 57

    return 1;
58 59
}

Mike Jones's avatar
Mike Jones committed
60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79
sub _set_resource_auth_token {
    my $self  = shift;

    # Set the auth token against every available resource class after a
    # successful login to the Mattermost server
    foreach my $resource (@{$self->api->resources}) {
        $resource->auth_token($self->auth_token);
    }

    return 1;
}

################################################################################

sub _build_api {
    my $self = shift;

    my $args = {
        base_url   => $self->base_url,
        auth_token => $self->auth_token,
80
        debug      => $self->debug,
Mike Jones's avatar
Mike Jones committed
81 82 83 84 85 86 87 88 89
    };

    my $ver = 'WebService::Mattermost::V4::API';

    # Later, if $self->api_version == 5 ...

    return $ver->new($args);
}

90 91
################################################################################

Mike Jones's avatar
Mike Jones committed
92
1;
Mike Jones's avatar
Mike Jones committed
93 94 95 96
__END__

=head1 NAME

97
WebService::Mattermost - a SDK for interacting with Mattermost.
Mike Jones's avatar
Mike Jones committed
98 99 100

=head1 DESCRIPTION

101 102
WebService::Mattermost provides websocket and REST API integrations for Mattermost,
and supercedes C<Net::Mattermost::Bot>, replacing all functionality.
Mike Jones's avatar
Mike Jones committed
103 104 105

=head2 SYNOPSIS

Mike Jones's avatar
Mike Jones committed
106
See C<WebService::Mattermost::V4::API> for all available API integrations.
Mike Jones's avatar
Mike Jones committed
107

108
    use WebService::Mattermost;
Mike Jones's avatar
Mike Jones committed
109

110
    my $mm = WebService::Mattermost->new({
Mike Jones's avatar
Mike Jones committed
111 112 113 114
        # Required
        base_url => 'https://my.mattermost.server.com/api/v4/',

        # Optional
115 116
        authenticate => 1,            # Trigger a "login" to the Mattermost server
        debug        => 1,            # Debug via Mojo::Log
Mike Jones's avatar
Mike Jones committed
117 118 119 120 121 122 123 124
        username     => 'MyUsername', # Login credentials for the server
        password     => 'MyPassword',
    });

    # Example REST API calls
    my $emojis = $mm->api->emoji->custom;
    my $user   = $mm->api->users->search_by_email('someone@somewhere.com');

125 126 127 128 129 130 131 132 133
Where appropriate, a response object or list of objects may be returned. You can
access these via (using the custom emoji search above as an example):

    # First item only
    my $item = $emojis->item;

    # All items
    my $items = $emoji->items;

Mike Jones's avatar
Mike Jones committed
134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173
=head2 METHODS

This class has no public methods.

=head2 ATTRIBUTES

=over 4

=item C<base_url>

The base URL of your Mattermost server. Should contain the C</api/v4/> section.

=item C<username>

An optional username for logging into Mattermost.

=item C<password>

An optional password for logging into Mattermost.

=item C<authenticate>

If this value is true, an authentication attempt will be made against your
Mattermost server.

=item C<auth_token>

Set after a successful login and used for authentication for the successive API
calls.

=item C<api>

A containing class for the available resources for API version 4.

=back

=head1 SEE ALSO

=over 4

Mike Jones's avatar
Mike Jones committed
174 175
=item L<Bug tracker and source|https://git.netsplit.uk/mike/WebService-Mattermost>

Mike Jones's avatar
Mike Jones committed
176 177 178 179
=item L<https://api.mattermost.com/>

Plain Mattermost API documentation.

Mike Jones's avatar
Mike Jones committed
180
=item C<WebService::Mattermost::V4::API>
Mike Jones's avatar
Mike Jones committed
181 182 183 184

Containing object for resources for version 4 of the Mattermost REST API.
Accessible from this class via the C<api> attribute.

185 186 187 188
=item C<Net::Mattermost::Bot>

Deprecated original library.

Mike Jones's avatar
Mike Jones committed
189 190 191 192 193 194
=back

=head1 AUTHOR

Mike Jones L<email:mike@netsplit.org.uk>