File Coverage

blib/lib/WebService/Mattermost.pm
Criterion Covered Total %
statement 33 34 97.0
branch 9 10 90.0
condition 10 12 83.3
subroutine 7 7 100.0
pod 0 1 0.0
total 59 64 92.1


line stmt bran cond sub pod time code
1             package WebService::Mattermost;
2:
3: # ABSTRACT: Perl client library for Mattermost's REST API and websocket gateway 4:
5: use Moo;
6: use Types::Standard qw(Bool Int Object Str);
7:
8: use WebService::Mattermost::V4::API;
9:
10: our $VERSION = 0.28;
11:
12: ################################################################################
 13:
14: has [ qw(base_url username password) ] => (is => 'ro', isa => Str, required => 1);
15:
16: has api_version => (is => 'ro', isa => Int, default => 4);
17: has [ qw(authenticate debug) ] => (is => 'rw', isa => Bool, default => 0);
18: has [ qw(auth_token user_id) ] => (is => 'rw', isa => Str, default => q{});
19:
20: has api => (is => 'ro', isa => Object, lazy => 1, builder => 1, clearer => 1);
21:
22: ################################################################################
 23:
24: sub BUILD {
25: my $self = shift;
26:
27: unless ($self->auth_token) {
28: $self->_try_authentication();
29: }
30:
31: return 1;
32: }
33:
34: ################################################################################
 35:
36: sub _try_authentication {
37: my $self = shift;
38:
39: if ($self->authenticate && $self->username && $self->password) {
40: # Log into Mattermost at runtime. The entire API requires an auth token
 41: # which is sent back from the login method.
 42: my $ret = $self->api->users->login($self->username, $self->password);
43:
44: if ($ret->is_success) {
45: $self->auth_token($ret->headers->header('Token'));
46: $self->user_id($ret->content->{id});
47: $self->_set_resource_auth_token();
48: $self->clear_api; # Force the API to be rebuilt with the new token
49: } else {
50: die $ret->message;
51: }
52: } elsif ($self->authenticate && !($self->username && $self->password)) {
53: die '"username" and "password" are required attributes for authentication';
54: } elsif ($self->auth_token) {
55: $self->_set_resource_auth_token();
56: }
57:
58: return 1;
59: }
60:
61: sub _set_resource_auth_token {
62: my $self = shift;
63:
64: # Set the auth token against every available resource class after a
 65: # successful login to the Mattermost server
 66: foreach my $resource (@{$self->api->resources}) {
67: $resource->auth_token($self->auth_token);
68: }
69:
70: return 1;
71: }
72:
73: ################################################################################
 74:
75: sub _build_api {
76: my $self = shift;
77:
78: my $args = {
79: base_url => $self->base_url,
80: auth_token => $self->auth_token,
81: debug => $self->debug,
82: };
83:
84: my $ver = 'WebService::Mattermost::V4::API';
85:
86: # Later, if $self->api_version == 5 ...
 87:
88: return $ver->new($args);
89: }
90:
91: ################################################################################
 92:
93: 1;
94:
95: __END__
96:
97: =pod
 98:
99: =encoding UTF-8
100:
101: =head1 NAME
102:
103: WebService::Mattermost - Perl client library for Mattermost's REST API and websocket gateway
104:
105: =head1 VERSION
106:
107: version 0.28
108:
109: =head1 DESCRIPTION
110:
111: WebService::Mattermost provides websocket and REST API integrations for Mattermost,
112: and supercedes C<Net::Mattermost::Bot>, replacing all functionality.
113:
114: See the L<repository|https://github.com/n7st/webservice-mattermost> for more
115: information.
116:
117: =head2 SYNOPSIS
118:
119: See L<WebService::Mattermost::V4::API> for all available API integrations.
120:
121: use WebService::Mattermost;
122:
123: my $mm = WebService::Mattermost->new({
124: # Required
125: base_url => 'https://my.mattermost.server.com/api/v4/',
126:
127: # Optional
128: authenticate => 1, # Trigger a "login" to the Mattermost server
129: debug => 1, # Debug via Mojo::Log
130: username => 'MyUsername', # Login credentials for the server
131: password => 'MyPassword',
132: });
133:
134: # Example REST API calls
135: my $emojis = $mm->api->emoji->custom;
136: my $user = $mm->api->users->search_by_email('someone@somewhere.com');
137:
138: Where appropriate, a response object or list of objects may be returned. You can
139: access these via (using the custom emoji search above as an example):
140:
141: # First item only
142: my $item = $emojis->item;
143:
144: # All items
145: my $items = $emoji->items;
146:
147: =head2 METHODS
148:
149: This class has no public methods.
150:
151: =head2 ATTRIBUTES
152:
153: =over 4
154:
155: =item C<base_url>
156:
157: The base URL of your Mattermost server. Should contain the C</api/v4/> section.
158:
159: =item C<username>
160:
161: An optional username for logging into Mattermost.
162:
163: =item C<password>
164:
165: An optional password for logging into Mattermost.
166:
167: =item C<authenticate>
168:
169: If this value is true, an authentication attempt will be made against your
170: Mattermost server.
171:
172: =item C<auth_token>
173:
174: Set after a successful login and used for authentication for the successive API
175: calls.
176:
177: =item C<api>
178:
179: A containing class for the available resources for API version 4.
180:
181: =back
182:
183: =head1 SEE ALSO
184:
185: =over 4
186:
187: =item L<Bug tracker and source|https://github.com/n7st/webservice-mattermost>
188:
189: =item L<https://api.mattermost.com/>
190:
191: Plain Mattermost API documentation.
192:
193: =item L<WebService::Mattermost::V4::API>
194:
195: Containing object for resources for version 4 of the Mattermost REST API.
196: Accessible from this class via the C<api> attribute.
197:
198: =back
199:
200: =head1 AUTHOR
201:
202: Mike Jones <mike@netsplit.org.uk>
203:
204: =head1 COPYRIGHT AND LICENSE
205:
206: This software is Copyright (c) 2020 by Mike Jones.
207:
208: This is free software, licensed under:
209:
210: The MIT (X11) License
211:
212: =cut
213: