File Coverage

blib/lib/WebService/Mattermost/V4/API/Resource/Users.pm
Criterion Covered Total %
statement 3 31 9.6
branch n/a
condition n/a
subroutine 1 10 10.0
pod 7 9 77.7
total 11 50 22.0


line stmt bran cond sub pod time code
1             package WebService::Mattermost::V4::API::Resource::Users;
2:
3: # ABSTRACT: Wrapped API methods for the users API endpoints. 4:
5: use Moo;
6:
7: extends 'WebService::Mattermost::V4::API::Resource';
8: with 'WebService::Mattermost::V4::API::Resource::Role::View::User';
9:
10: ################################################################################
 11:
12: around [ qw(get_by_username check_mfa_by_username) ] => sub {
13: my $orig = shift;
14: my $self = shift;
15: my $username = shift;
16:
17: unless ($username) {
18: return $self->error_return('Invalid or missing username parameter');
19: }
20:
21: return $self->$orig($username, @_);
22: };
23:
24: around [ qw(get_by_email send_password_reset_email) ] => sub {
25: my $orig = shift;
26: my $self = shift;
27: my $email = shift;
28:
29: unless ($email) {
30: return $self->error_return('Invalid or missing email parameter');
31: }
32:
33: return $self->$orig($email, @_);
34: };
35:
36: around [ qw(
 37: disable_personal_access_token
 38: enable_personal_access_token
 39: get_user_access_token
 40: ) ] => sub {
41: my $orig = shift;
42: my $self = shift;
43: my $token = shift;
44:
45: unless ($token) {
46: return $self->error_return('Invalid or missing token parameter');
47: }
48:
49: return $self->$orig($token, @_);
50: };
51:
52: ################################################################################
 53:
54: sub login {
55: my $self = shift;
56: my $username = shift;
57: my $password = shift;
58:
59: return $self->_single_view_post({
60: endpoint => 'login',
61: parameters => {
62: login_id => $username,
63: password => $password,
64: },
65: });
66: }
67:
68: sub create {
69: my $self = shift;
70: my $args = shift;
71:
72: return $self->_post({
73: parameters => $args,
74: required => [ qw(username password email) ],
75: });
76: }
77:
78: sub list {
79: my $self = shift;
80: my $args = shift;
81:
82: return $self->_get({ parameters => $args });
83: }
84:
85: sub list_by_ids {
86: my $self = shift;
87: my $ids = shift;
88:
89: return $self->_call({
90: endpoint => 'ids',
91: method => $self->post,
92: parameters => $ids,
93: });
94: }
95:
96: sub list_by_usernames {
97: my $self = shift;
98: my $usernames = shift;
99:
100: return $self->_post({
101: endpoint => 'usernames',
102: parameters => $usernames,
103: });
104: }
105:
106: sub search {
107: my $self = shift;
108: my $args = shift;
109:
110: return $self->_post({
111: endpoint => 'search',
112: parameters => $args,
113: required => [ 'term' ],
114: });
115: }
116:
117: sub autocomplete {
118: my $self = shift;
119: my $args = shift;
120:
121: return $self->_get({
122: endpoint => 'autocomplete',
123: parameters => $args,
124: required => [ 'name' ],
125: });
126: }
127:
128: sub get_by_username {
129: my $self = shift;
130: my $username = shift;
131:
132: return $self->_single_view_get({
133: endpoint => 'username/%s',
134: ids => [ $username ],
135: });
136: }
137:
138: sub reset_password {
139: my $self = shift;
140: my $args = shift;
141:
142: return $self->_post({
143: endpoint => 'password/reset',
144: parameters => $args,
145: required => [ qw(code new_password) ],
146: });
147: }
148:
149: sub check_mfa_by_username {
150: my $self = shift;
151: my $username = shift;
152:
153: return $self->_post({
154: endpoint => 'mfa',
155: parameters => {
156: login_id => $username,
157: },
158: });
159: }
160:
161: sub send_password_reset_email {
162: my $self = shift;
163: my $email = shift;
164:
165: return $self->_post({
166: endpoint => 'password/reset/send',
167: parameters => {
168: email => $email,
169: },
170: });
171: }
172:
173: sub get_by_email {
174: my $self = shift;
175: my $email = shift;
176:
177: return $self->_get({
178: endpoint => 'email/%s',
179: ids => [ $email ],
180: });
181: }
182:
183: sub get_user_access_token {
184: my $self = shift;
185: my $id = shift;
186:
187: return $self->_get({
188: endpoint => 'tokens/%s',
189: ids => [ $id ],
190: });
191: }
192:
193: sub disable_personal_access_token {
194: my $self = shift;
195: my $id = shift;
196:
197: return $self->_post({
198: endpoint => 'tokens/disable',
199: parameters => {
200: token => $id,
201: },
202: });
203: }
204:
205: sub enable_personal_access_token {
206: my $self = shift;
207: my $id = shift;
208:
209: return $self->_post({
210: endpoint => 'tokens/enable',
211: parameters => {
212: token => $id,
213: },
214: });
215: }
216:
217: sub search_tokens {
218: my $self = shift;
219: my $term = shift;
220:
221: return $self->_post({
222: endpoint => 'tokens/search',
223: parameters => {
224: term => $term,
225: },
226: });
227: }
228:
229: ################################################################################
230:
231: 1;
232:
233: __END__
234:
235: =pod
236:
237: =encoding UTF-8
238:
239: =head1 NAME
240:
241: WebService::Mattermost::V4::API::Resource::Users - Wrapped API methods for the users API endpoints.
242:
243: =head1 VERSION
244:
245: version 0.30
246:
247: =head1 DESCRIPTION
248:
249: =head2 USAGE
250:
251: use WebService::Mattermost;
252:
253: my $mm = WebService::Mattermost->new({
254: authenticate => 1,
255: username => 'me@somewhere.com',
256: password => 'hunter2',
257: base_url => 'https://my.mattermost.server.com/api/v4/',
258: });
259:
260: my $resource = $mm->api->users;
261:
262: =head2 METHODS
263:
264: =over 4
265:
266: =item C<login()>
267:
268: L<Authentication|https://api.mattermost.com/#tag/authentication>
269:
270: Log into the Mattermost server using a username and password.
271:
272: my $response = $resource->login({
273: username => 'USERNAME-HERE',
274: password => 'PASSWORD-HERE',
275: });
276:
277: =item C<create()>
278:
279: L<Create a user|https://api.mattermost.com/#tag/users%2Fpaths%2F~1users%2Fpost>
280:
281: Create a new user on the server.
282:
283: my $response = $resource->create({
284: # Required parameters:
285: email => '...',
286: username => '...',
287: password => '...',
288:
289: # Optional parameters:
290: first_name => '...',
291: last_name => '...',
292: nickname => '...',
293: locale => '...',
294: props => {
295: # ...
296: },
297: notify_props => {
298: # ...
299: },
300: });
301:
302: =item C<list()>
303:
304: L<Get users|https://api.mattermost.com/#tag/users%2Fpaths%2F~1users%2Fget>
305:
306: my $response = $resource->list({
307: # Optional parameters:
308: page => 0,
309: per_page => 60,
310: in_team => 'TEAM-ID-HERE',
311: not_in_team => 'TEAM-ID-HERE',
312: in_channel => 'CHANNEL-ID-HERE',
313: not_in_channel => 'CHANNEL-ID-HERE',
314: without_team => \1,
315: sort => 'STRING',
316: });
317:
318: =item C<list_by_ids()>
319:
320: L<Get users by IDs|https://api.mattermost.com/#tag/users%2Fpaths%2F~1users~1ids%2Fpost>
321:
322: Takes an ArrayRef of IDs as its only argument.
323:
324: my $users = $resource->list_by_ids([ qw(
325: USER-ID-1
326: USER-ID-2
327: USER-ID-3
328: ) ]);
329:
330: =item C<list_by_usernames()>
331:
332: L<Get by usernames|https://api.mattermost.com/#tag/users%2Fpaths%2F~1users~1usernames%2Fpost>
333:
334: Takes an ArrayRef of usernames.
335:
336: my $users = $resource->list_by_usernames([ qw(
337: USERNAME-1
338: USERNAME-2
339: USERNAME-3
340: ) ]);
341:
342: =item C<search()>
343:
344: L<Search users|https://api.mattermost.com/#tag/users%2Fpaths%2F~1users~1search%2Fpost>
345:
346: my $response = $resource->search({
347: # Required parameters:
348: term => 'SEARCH-TERM-HERE',
349:
350: # Optional parameters:
351: team_id => 'TEAM-ID-HERE',
352: not_in_team_id => 'TEAM-ID-HERE',
353: in_channel_id => 'CHANNEL-ID-HERE',
354: not_in_channel_id => 'CHANNEL-ID-HERE',
355: allow_inactive => \1, # or \0 - true/false
356: without_team => \1,
357: sort => 'STRING',
358: });
359:
360: =item C<autocomplete()>
361:
362: L<Autocomplete users|https://api.mattermost.com/#tag/users%2Fpaths%2F~1users~1autocomplete%2Fget>
363:
364: my $response = $resource->autocomplete({
365: # Required parameters:
366: name => 'USERNAME-HERE',
367:
368: # Optional parameters:
369: team_id => 'TEAM-ID-HERE',
370: channel_id => 'CHANNEL-ID-HERE',
371: });
372:
373: =item C<get_by_username()>
374:
375: L<Get a user by username|https://api.mattermost.com/#tag/users%2Fpaths%2F~1users~1username~1%7Busername%7D%2Fget>
376:
377: Get a user by their username (exact match only).
378:
379: my $response = $resource->get_by_username('mike');
380:
381: =item C<reset_password_by_id()>
382:
383: L<Reset password|https://api.mattermost.com/#tag/users%2Fpaths%2F~1users~1password~1reset%2Fpost>
384:
385: Reset a user's password. Requires a recovery code.
386:
387: my $response = $resource->reset_password({
388: new_password => 'hunter2',
389: code => 1234
390: });
391:
392: =item C<check_mfa_by_username()>
393:
394: L<Check MFA|https://api.mattermost.com/#tag/users%2Fpaths%2F~1users~1mfa%2Fpost>
395:
396: Check whether a user requires multi-factor auth by username or email.
397:
398: my $response = $resource->check_mfa_by_username('USERNAME-HERE');
399:
400: =item C<send_password_reset_email()>
401:
402: L<Send password reset email|https://api.mattermost.com/#tag/users%2Fpaths%2F~1users~1password~1reset~1send%2Fpost>
403:
404: Send a password reset email.
405:
406: my $response = $resource->send_password_reset_email('me@somewhere.com');
407:
408: =item C<get_by_email()>
409:
410: L<Get a user by email|https://api.mattermost.com/#tag/users%2Fpaths%2F~1users~1email~1%7Bemail%7D%2Fget>
411:
412: Get a user by email address.
413:
414: my $response = $resource->get_by_email('me@somewhere.com');
415:
416: =back
417:
418: =head1 AUTHOR
419:
420: Mike Jones <mike@netsplit.org.uk>
421:
422: =head1 COPYRIGHT AND LICENSE
423:
424: This software is Copyright (c) 2023 by Mike Jones.
425:
426: This is free software, licensed under:
427:
428: The MIT (X11) License
429:
430: =cut
431: