package Kanboard::API; ## no critic
use v5.40;
use strict;
use Moo;
use JSON;
=head1 NAME
Kanboard::API - A Perl interface to the Kanboard API
=head1 VERSION
Version 0.01
=cut
our $VERSION = '0.01';
=head1 SYNOPSIS
Kanboard::API is a Perl interface to the Kanboard API. It provides a simple way to interact with a Kanboard instance.
use Kanboard::API;
my $kanboard = Kanboard::API->new(username => 'yourusername|jsonrpc', password => 'apikey', endpoint => 'https://yourkanboardinstance.com');
...
=head1 ATTRIBUTES
=head2 username
The username to use for authentication. Defaults to "jsonrpc".
=cut
has username => ( is => 'ro', default => 'jsonrpc' );
=head2 password
The password to use for authentication.
=cut
has password => ( is => 'ro', required => 1 );
=head2 endpoint
The JSON RPC Endpoint of the Kanboard instance.
=cut
has endpoint => ( is => 'ro', required => 1 );
=head2 ua
The LWP::UserAgent object used to make requests.
=cut
has 'ua' => (
is => 'lazy',
builder => sub { LWP::UserAgent->new },
);
=head1 PRIVATE METHODS
=head2 _request
=cut
sub _request( $self, $method, $params = [] ) {
my $auth = encode_base64( "$self->{username}:$self->{password}", "" );
my $headers = [
'Content-Type' => 'application/json',
'Authorization' => "Basic $auth",
];
my $request_json = {
jsonrpc => "2.0",
id => 1,
method => $method,
params => $params // [],
};
my $body = encode_json($request_json);
my $request =
HTTP::Request->new( 'POST', $self->endpoint, $headers, $body );
my $response = $self->ua->request($request);
if ( $response->is_success ) {
my $content = $response->decoded_content;
my $content_json = decode_json($content);
if ( $content_json->{error} ) {
die
"$content_json->{error}{message} - $content_json->{error}{data}";
}
return $content_json->{result};
}
else {
die $response->status_line;
}
}
=head1 PUBLIC METHODS
=head2 get_version
Purpose: Get the application version
Parameters: none
Result: version (Example: 1.0.12, master)
=cut
sub get_version( $self) {
return $self->_request('getVersion');
}
=head2 get_me
Purpose: Get the current user profile
Parameters:
None
Result on success: user properties
Result on failure: empty list
=cut
sub get_me( $self) {
return $self->_request('getMe');
}
=head2 create_project
Purpose: Create a new project
Parameters:
name (string, required)
description (string, optional)
owner_id (integer, optional)
identifier (string, optional)
Result on success: project ID
Result on failure: false
=cut
sub create_project( $self, $params) {
return $self->_request('createProject', $params);
}
=head2 remove_project
Purpose: Remove a project
Parameters:
project_id (integer, required)
Result on success: true
Result on failure: false
=cut
sub remove_project( $self, $params) {
return $self->_request('removeProject', $params);
}
=head2 get_project
Purpose: Get project details
Parameters:
project_id (integer, required)
Result on success: project properties
Result on failure: empty list
=cut
sub get_project( $self, $params) {
return $self->_request('getProject', $params);
}
=head2 create_task
Purpose: Create a new task
Parameters:
title (string, required)
project_id (integer, required)
description (string, optional)
category_id (integer, optional)
owner_id (integer, optional)
color_id (string, optional)
column_id (integer, optional)
swimlane_id (integer, optional)
priority (integer, optional)
date_due (timestamp, optional)
Result on success: task ID
Result on failure: false
=cut
sub create_task( $self, $params) {
return $self->_request('createTask', $params);
}
=head2 remove_task
Purpose: Remove a task
Parameters:
task_id (integer, required)
Result on success: true
Result on failure: false
=cut
sub remove_task( $self, $params) {
return $self->_request('removeTask', $params);
}
=head2 get_task
Purpose: Get task details
Parameters:
task_id (integer, required)
Result on success: task properties
Result on failure: empty list
=cut
sub get_task( $self, $params) {
return $self->_request('getTask', $params);
}
=head2 get_all_tasks
Purpose: Get all tasks for a project
Parameters:
project_id (integer, required)
Result on success: list of tasks
Result on failure: empty list
=cut
sub get_all_tasks( $self, $params) {
return $self->_request('getAllTasks', $params);
}
=head2 get_board
Purpose: Get all necessary information to display a board
Parameters:
project_id (integer, required)
Result on success: board properties
Result on failure: empty list
=cut
sub get_board( $self, $params) {
return $self->_request('getBoard', $params);
}
=head1 AUTHOR
Dan Barbarito, C<< <dan at barbarito.me> >>
=head1 BUGS
Please report any bugs or feature requests to C<bug-kanboard-api at rt.cpan.org>, or through
the web interface at L<https://rt.cpan.org/NoAuth/ReportBug.html?Queue=Kanboard-API>. I will be notified, and then you'll
automatically be notified of progress on your bug as I make changes.
=head1 SUPPORT
You can find documentation for this module with the perldoc command.
perldoc Kanboard::API
You can also look for information at:
=over 4
=item * RT: CPAN's request tracker (report bugs here)
=item * CPAN Ratings
=item * Search CPAN
=back
=head1 ACKNOWLEDGEMENTS
=head1 LICENSE AND COPYRIGHT
This software is Copyright (c) 2024 by Dan Barbarito.
This is free software, licensed under:
The Artistic License 2.0 (GPL Compatible)
=cut
1; # End of Kanboard::API