NAME CPANLists::Server - Application that runs on cpanlists.org VERSION This document describes version 0.02 of CPANLists::Server (from Perl distribution CPANLists-Server), released on 2014-05-17. SYNOPSIS You probably do not want to install this. This distribution contains the code to run on cpanlists.org. For the client program, see App::cpanlists. DESCRIPTION Currently to use this module, you have to do two things. This is ugly and might change in the future. * Set database handle at startup $dbh = DBI->connect(...); CPANLists::Server::__dbh($dbh); * Set PSGI environment for each request Mainly so that __activity_log() can get REMOTE_ADDR etc from PSGI environment. CPANLists::Server::__env($env); FUNCTIONS add_item(%args) -> [status, msg, result, meta] Add an item to a list. Arguments ('*' denotes required arguments): * comment => *str* Comment. Will be interpreted as Markdown * list_id* => *int* * name* => *str* Item's name (i.e. module name/CPAN ID). * rating => *int* Rating. Return value: Returns an enveloped result (an array). First element (status) is an integer containing HTTP status code (200 means OK, 4xx caller error, 5xx function error). Second element (msg) is a string containing error message, or 'OK' if status is 200. Third element (result) is optional, the actual result. Fourth element (meta) is called result metadata and is optional, a hash that contains extra information. add_list_comment(%args) -> [status, msg, result, meta] Add a comment to a list. Arguments ('*' denotes required arguments): * comment* => *str* Comment. Will be interpreted as Markdown * list_id* => *int* Return value: Returns an enveloped result (an array). First element (status) is an integer containing HTTP status code (200 means OK, 4xx caller error, 5xx function error). Second element (msg) is a string containing error message, or 'OK' if status is 200. Third element (result) is optional, the actual result. Fourth element (meta) is called result metadata and is optional, a hash that contains extra information. auth_user(%args) -> [status, msg, result, meta] Check username and password against database. Upon success, will return a hash of information, currently: "id" (user numeric ID), "email". Arguments ('*' denotes required arguments): * password* => *str* * username* => *str* Return value: Returns an enveloped result (an array). First element (status) is an integer containing HTTP status code (200 means OK, 4xx caller error, 5xx function error). Second element (msg) is a string containing error message, or 'OK' if status is 200. Third element (result) is optional, the actual result. Fourth element (meta) is called result metadata and is optional, a hash that contains extra information. check_session(%args) -> [status, msg, result, meta] Check if session with certain ID exists and not expired. Arguments ('*' denotes required arguments): * id* => *str* Return value: Returns an enveloped result (an array). First element (status) is an integer containing HTTP status code (200 means OK, 4xx caller error, 5xx function error). Second element (msg) is a string containing error message, or 'OK' if status is 200. Third element (result) is optional, the actual result. Fourth element (meta) is called result metadata and is optional, a hash that contains extra information. Session information (any) create_list(%args) -> [status, msg, result, meta] Create a new list. Arguments ('*' denotes required arguments): * description => *str* A longer (one to several paragraphs) of description. Will be interpreted as Markdown. For module lists, module names in the form of "Foo::bar" or "mod://Foo::bar" or "mod://foo" will be detected and added as items if indeed are CPAN module names. * items => *array* List items. Alternatively, you can leave this empty and add items one-by-one using add_item(). * name* => *str* The list title. Examples: "Steven's most favorite modules", "Steven's favorite authors", "Modules to do blah", "Top ten modules you'll want for christmas 2014". * scan_modules_from_description => *bool* (default: 0) Whether to scan module names from description and add them as items (for module lists only). * tags => *array* Tags. * type* => *str* List type, either m (for modules) or a (authors). Return value: Returns an enveloped result (an array). First element (status) is an integer containing HTTP status code (200 means OK, 4xx caller error, 5xx function error). Second element (msg) is a string containing error message, or 'OK' if status is 200. Third element (result) is optional, the actual result. Fourth element (meta) is called result metadata and is optional, a hash that contains extra information. create_or_get_session(%args) -> [status, msg, result, meta] Arguments ('*' denotes required arguments): * username* => *str* Return value: Returns an enveloped result (an array). First element (status) is an integer containing HTTP status code (200 means OK, 4xx caller error, 5xx function error). Second element (msg) is a string containing error message, or 'OK' if status is 200. Third element (result) is optional, the actual result. Fourth element (meta) is called result metadata and is optional, a hash that contains extra information. create_user(%args) -> [status, msg, result, meta] Arguments ('*' denotes required arguments): * email* => *str* * first_name => *str* * last_name => *str* * note => *str* * password* => *str* * username* => *str* Return value: Returns an enveloped result (an array). First element (status) is an integer containing HTTP status code (200 means OK, 4xx caller error, 5xx function error). Second element (msg) is a string containing error message, or 'OK' if status is 200. Third element (result) is optional, the actual result. Fourth element (meta) is called result metadata and is optional, a hash that contains extra information. delete_item(%args) -> [status, msg, result, meta] Delete an item from a list. Arguments ('*' denotes required arguments): * list_id* => *int* * name* => *str* Item's name (i.e. module name/CPAN ID). Return value: Returns an enveloped result (an array). First element (status) is an integer containing HTTP status code (200 means OK, 4xx caller error, 5xx function error). Second element (msg) is a string containing error message, or 'OK' if status is 200. Third element (result) is optional, the actual result. Fourth element (meta) is called result metadata and is optional, a hash that contains extra information. delete_list(%args) -> [status, msg, result, meta] Delete a list. Arguments ('*' denotes required arguments): * id* => *int* * reason => *str* Optional reason for deletion. Return value: Returns an enveloped result (an array). First element (status) is an integer containing HTTP status code (200 means OK, 4xx caller error, 5xx function error). Second element (msg) is a string containing error message, or 'OK' if status is 200. Third element (result) is optional, the actual result. Fourth element (meta) is called result metadata and is optional, a hash that contains extra information. delete_list_comment(%args) -> [status, msg, result, meta] Delete a single list comment. Arguments ('*' denotes required arguments): * id* => *int* * reason => *str* Optional reason for deletion. Return value: Returns an enveloped result (an array). First element (status) is an integer containing HTTP status code (200 means OK, 4xx caller error, 5xx function error). Second element (msg) is a string containing error message, or 'OK' if status is 200. Third element (result) is optional, the actual result. Fourth element (meta) is called result metadata and is optional, a hash that contains extra information. get_bitcard_signin_url() -> [status, msg, result, meta] Get signin URL via BitCard API (bitcard.org). To signin via BitCard, first call this function. You will get login URL (to bitcard.org). Go to the login URL and enter your credentials. Afterwards, if the login is correct, you will get return URL like, which you need to follow: https://cpanlists.org/api/verify_bitcard_signin?bc_confirmed=1&... Either follow this URL, or pass the parameters to the "verify_bitcard_signin" function yourself. If signin is verified, a success status (200) will be returned along with session ID to use. Session ID can be used as password in HTTP authenticaion e.g.: curl -u USERNAME:SESSION_ID https://cpanlists.org/api/SOME_FUNC?PARAM1=... By default session ID can be used for 6 (six) months. If session is expired, you can signin again. No arguments. Return value: Returns an enveloped result (an array). First element (status) is an integer containing HTTP status code (200 means OK, 4xx caller error, 5xx function error). Second element (msg) is a string containing error message, or 'OK' if status is 200. Third element (result) is optional, the actual result. Fourth element (meta) is called result metadata and is optional, a hash that contains extra information. get_list(%args) -> [status, msg, result, meta] Get details about a list. Arguments ('*' denotes required arguments): * id* => *int* * items => *bool* (default: 1) Whether to retrieve list's items. Return value: Returns an enveloped result (an array). First element (status) is an integer containing HTTP status code (200 means OK, 4xx caller error, 5xx function error). Second element (msg) is a string containing error message, or 'OK' if status is 200. Third element (result) is optional, the actual result. Fourth element (meta) is called result metadata and is optional, a hash that contains extra information. get_list_comment(%args) -> [status, msg, result, meta] Get a single list comment. Arguments ('*' denotes required arguments): * id* => *int* Return value: Returns an enveloped result (an array). First element (status) is an integer containing HTTP status code (200 means OK, 4xx caller error, 5xx function error). Second element (msg) is a string containing error message, or 'OK' if status is 200. Third element (result) is optional, the actual result. Fourth element (meta) is called result metadata and is optional, a hash that contains extra information. get_user(%args) -> [status, msg, result, meta] Get user information either by email or username. Arguments ('*' denotes required arguments): * email => *str* * username => *str* Return value: Returns an enveloped result (an array). First element (status) is an integer containing HTTP status code (200 means OK, 4xx caller error, 5xx function error). Second element (msg) is a string containing error message, or 'OK' if status is 200. Third element (result) is optional, the actual result. Fourth element (meta) is called result metadata and is optional, a hash that contains extra information. like_list(%args) -> [status, msg, result, meta] Like a list. You are allowed to like your own list. Arguments ('*' denotes required arguments): * id* => *int* List ID. Return value: Returns an enveloped result (an array). First element (status) is an integer containing HTTP status code (200 means OK, 4xx caller error, 5xx function error). Second element (msg) is a string containing error message, or 'OK' if status is 200. Third element (result) is optional, the actual result. Fourth element (meta) is called result metadata and is optional, a hash that contains extra information. list_items(%args) -> [status, msg, result, meta] List items of a list. Arguments ('*' denotes required arguments): * list_id* => *int* Return value: Returns an enveloped result (an array). First element (status) is an integer containing HTTP status code (200 means OK, 4xx caller error, 5xx function error). Second element (msg) is a string containing error message, or 'OK' if status is 200. Third element (result) is optional, the actual result. Fourth element (meta) is called result metadata and is optional, a hash that contains extra information. list_list_comments(%args) -> [status, msg, result, meta] List comments to a list. Arguments ('*' denotes required arguments): * id => *int* * list_id* => *int* Return value: Returns an enveloped result (an array). First element (status) is an integer containing HTTP status code (200 means OK, 4xx caller error, 5xx function error). Second element (msg) is a string containing error message, or 'OK' if status is 200. Third element (result) is optional, the actual result. Fourth element (meta) is called result metadata and is optional, a hash that contains extra information. list_lists(%args) -> [status, msg, result, meta] List available lists. Arguments ('*' denotes required arguments): * creator => *str* * has_tags => *array* Only include lists containing these tags. * id => *int* * lacks_tags => *array* Only include lists not containing these tags. * query => *str* * result_limit => *int* (default: 5000) Limit number of results. * type => *str* Filter only certain type of lists ("a" means lists of authors only, "m" means lists of modules only). Return value: Returns an enveloped result (an array). First element (status) is an integer containing HTTP status code (200 means OK, 4xx caller error, 5xx function error). Second element (msg) is a string containing error message, or 'OK' if status is 200. Third element (result) is optional, the actual result. Fourth element (meta) is called result metadata and is optional, a hash that contains extra information. unlike_list(%args) -> [status, msg, result, meta] Unlike a list. Arguments ('*' denotes required arguments): * id* => *int* List ID. Return value: Returns an enveloped result (an array). First element (status) is an integer containing HTTP status code (200 means OK, 4xx caller error, 5xx function error). Second element (msg) is a string containing error message, or 'OK' if status is 200. Third element (result) is optional, the actual result. Fourth element (meta) is called result metadata and is optional, a hash that contains extra information. update_item(%args) -> [status, msg, result, meta] Update a list item. Arguments ('*' denotes required arguments): * list_id* => *int* * name* => *str* Item's name. * new_comment => *str* Item's new comment. If not specified, comment will not be changed * new_rating => *str* Item's new rating. If not specified, rating will not be changed Return value: Returns an enveloped result (an array). First element (status) is an integer containing HTTP status code (200 means OK, 4xx caller error, 5xx function error). Second element (msg) is a string containing error message, or 'OK' if status is 200. Third element (result) is optional, the actual result. Fourth element (meta) is called result metadata and is optional, a hash that contains extra information. update_list(%args) -> [status, msg, result, meta] Update a list. Arguments ('*' denotes required arguments): * id* => *int* * new_description => *str* List's new description. If not specified, description will not be changed * new_items => *array* List's new items. If not specified, items will not be changed * new_name => *str* List's new name. If not specified, name will not be changed * new_tags => *array* List's new tags. If not specified, tags will not be changed Return value: Returns an enveloped result (an array). First element (status) is an integer containing HTTP status code (200 means OK, 4xx caller error, 5xx function error). Second element (msg) is a string containing error message, or 'OK' if status is 200. Third element (result) is optional, the actual result. Fourth element (meta) is called result metadata and is optional, a hash that contains extra information. update_list_comment(%args) -> [status, msg, result, meta] Update a list comment. Arguments ('*' denotes required arguments): * id* => *int* * new_comment => *str* Comment. If not specified, comment will not be replaced. Will be interpreted as Markdown. Return value: Returns an enveloped result (an array). First element (status) is an integer containing HTTP status code (200 means OK, 4xx caller error, 5xx function error). Second element (msg) is a string containing error message, or 'OK' if status is 200. Third element (result) is optional, the actual result. Fourth element (meta) is called result metadata and is optional, a hash that contains extra information. verify_bitcard_signin(%args) -> [status, msg, result, meta] Verify URL parameters returned by BitCard. See "get_bitcard_signin_url" for more information on signing in via BitCard. Arguments ('*' denotes required arguments): * bc_confirmed => *any* * bc_email => *any* * bc_fields => *any* * bc_id => *any* * bc_name => *any* * bc_sig => *any* * bc_ts => *any* * bc_username => *any* * bc_version => *any* Return value: Returns an enveloped result (an array). First element (status) is an integer containing HTTP status code (200 means OK, 4xx caller error, 5xx function error). Second element (msg) is a string containing error message, or 'OK' if status is 200. Third element (result) is optional, the actual result. Fourth element (meta) is called result metadata and is optional, a hash that contains extra information. Session ID (hash) =head1 TODO SEE ALSO App::cpanlists HOMEPAGE Please visit the project's homepage at . SOURCE Source repository is at . BUGS Please report any bugs or feature requests on the bugtracker website When submitting a bug or request, please include a test-file or a patch to an existing test-file that illustrates the bug or desired feature. AUTHOR Steven Haryanto COPYRIGHT AND LICENSE This software is copyright (c) 2014 by Steven Haryanto. This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.