/ 
WebService-HabitRPG-0.30
River stage one • 1 direct dependent • 1 total dependent
/ WebService::HabitRPG

NAME

WebService::HabitRPG - Perl interface to the HabitRPG (Habitica) API

VERSION

version 0.30

SYNOPSIS

use WebService::HabitRPG;

# The API Token and User ID are obained through the
# Setting -> API link on http://habitrpg.com/

my $hrpg = WebService::HabitRPG->new(
    api_token => 'your-token-goes-here',
    user_id   => 'your-user-id-goes-here',
    tags      => { work => $uuid, home => $uuid2, ... }, # optional
);

# Get everyting about the user
my $user = $hrpg->user;

# Get all tasks.
my $tasks = $hrpg->tasks;

# Get all tasks of a particular type (eg: 'dailys')
my $daily = $hrpg->tasks('dailys');

# Increment/decrement a task
$hrpg->up($task_id);
$hrpg->down($task_id);

# Make a new task
$hrpg->new_task(
    type => 'daily',
    text => 'floss teeth',
    up   => 1,
    down => 0,
);

DESCRIPTION

Interface to API provided by HabitRPG, also known as Habitica.

At the time of release, the HabitRPG API is still under construction. This module may change as a result.

Note that when data structures are returned, they are almost always straight conversions from the JSON returned by the HabitRPG API.

METHODS

new

my $hrpg = WebService::HabitRPG->new(
    api_token  => 'your-token-goes-here',
    user_id    => 'your-user-id-goes-here',
    tags       => { work => $work_uuid, home => $home_uuid, ... },
    tag_prefix => '^', # Optional, defaults to '^'
);

Creates a new WebService::HabitRPG object. The api_token and user_id parameters are mandatory. You may also pass your own WWW::Mechanize compatible user-agent with agent, and should you need it your own HabitRPG API base URL with api_base (useful for testing, or if you're running your own server).

By default, the official API base of https://habitica.com/api/v3 is used.

The tags field is optional, but if included should consist of tag = uuid> pairs. When API support is added for tags, this optional will become obsolete.

Use of the tags feature should be considered experimental.

user

my $user = $hrpg->user();

Returns everything from the /user route in the HabitRPG API. This is practically everything about the user, their tasks, scores, and other information.

The Perl data structure that is returned is a straight conversion from the JSON provided by the HabitRPG API.

tasks

my $tasks  = $hrpg->tasks();            # All tasks
my $habits = $hrpg->tasks('habits');    # Only habits

Return a reference to an array of tasks. With no arguments, all tasks (habits, dailies, todos and rewards) are returned. With an argument, only tasks of the given type are returned. The argument must be one of habits, dailys, todos or rewards.

NOTE: The singular forms habit, daily, todo, and reward are also accepted, but deprecated; they will be forbidden in a future release. Please take the time to update your code! A warning will be emitted if a "legacy" type is seen.

See WebService::HabitRPG::Task for a complete description of what task objects look like.

Not all tasks will have all fields. Using the hrpg command-line tool with hrpg dump tasks is a convenient way to see the data structures returned by this method.

get_task

my $task = $hrpg->get_task('6a11dd4d-c2d6-42b7-b9ff-f562d4ccce4e');

Given a task ID, returns information on that task in the same format at "tasks" above.

new_task

$hrpg->new_task(
    type      => 'daily',           # Required
    text      => 'floss teeth',     # Required
    up        => 1,                 # Suggested, defaults true
    down      => 0,                 # Suggested, defaults true
    value     => 0,
    note      => "Floss every tooth for great justice",
    completed => 0,
    extend    => {},
);

Creates a new task. Only the type and text arguments are required, all other tasks are optional. The up and down options default to true (ie, tasks can be both incremented and decremented).

The type parameter must be one of: habit, daily, todo or reward.

The extend parameter consists to key/value pairs that will be added to the JSON create packet. This should only be used if you know what you're doing, and wish to take advantage of new or undocumented features in the API.

Returns a task data structure of the task created, identical to the "tasks" method above.

Creating tasks that can be neither incremented nor decremented is of dubious usefulness.

updown

$hrpg->updown('6a11dd4d-c2d6-42b7-b9ff-f562d4ccce4e', 'up'  );
$hrpg->updown('6a11dd4d-c2d6-42b7-b9ff-f562d4ccce4e', 'down');

Moves the habit in the direction specified. Returns a data structure of character status:

{
    exp   => 11,
    gp    => 15.5,
    hp    => 50,
    lv    => 2,
    delta => 1,
}

up

$hrpg->up($task);

Convenience method. Equivalent to $hrpg-updown($task, 'up')>;

down

$hrpg->down($task);

Convenience method. Equivalent to $hrpg-updown($task, 'down')>;

_update

$hrpg->_update($task, { attr => value });

This method should be considered experimental.

Updates the given task on the server (using the underlying PUT functionality in the API). Attributes are not checked for sanity, they're just directly converted into JSON.

search_tasks

my @tasks = $hrpg->search_tasks($search_term, all => $bool);

# Eg:
my @tasks = $hrpg->search_tasks('floss');
my @tasks = $hrpg->search_tasks('git', all => 1);

Search for tasks which match the provided search term. If the search term exactly matches a task ID, then the task ID is returned. Otherwise, returns a list of tasks which contain the search term in their names (the text field returned by the API). This list is in the same format as the as the "tasks" method call.

If the term begins with the tag prefix character ('^' by default), it is considered to be a tag, and the hashless form is searched for. For example, '^work' will result in returning all tasks which match the tag 'work'.

If the term does not begin with a hash, then the search term is treated in a literal, case-insensitive fashion.

If the optional all parameter is set, then all tasks are returned. Otherwise only non-completed tasks are returned.

This is useful for providing a human-friendly way to refer to tasks. For example:

# Search for a user-provided term
my @tasks = $hrpg->search_tasks($term);

# Increment task if found
if (@tasks == 1) {
    $hrpg->up($tasks[0]->id);
}
else {
    say "Too few or too many tasks found.";
}

BUGS

I'm sure there are plenty! Please view and/or record them at https://github.com/pjf/WebService-HabitRPG/issues .

SEE ALSO

The HabitRPG API spec.

The hrpg command-line client. It's freakin' awesome.

AUTHOR

Paul Fenwick <pjf@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2013 by Paul Fenwick.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.