/ 
WebService-SlimTimer-0.005
River stage zero No dependents
/ WebService::SlimTimer

NAME

WebService::SlimTimer - Provides interface to SlimTimer web service.

VERSION

version 0.005

SYNOPSIS

This module provides interface to http://www.slimtimer.com/ functionality.

Notice that to use it you must obtain an API key by creating an account at SlimTimer web site and then visit http://slimtimer.com/help/api.

my $st = WebService::SlimTimer->new($api_key);
$st->login('your@email.address', 'secret-password');

# Create a brand new task.
my $task = $st->create_task('Testing SlimTimer');

# Spend 10 minutes on testing.
$st->create_entry($task->id, DateTime->now, DateTime->from_epoch(time() + 600));

# Mark the task as completed.
$st->complete_task($task->id, DateTime->now());

# Or maybe even get rid of it now.
$st->delete_task($task->id);

METHODS

CONSTRUCTOR

The single required constructor argument is the API key required to connect to SlimTimer:

my $st = WebService::SlimTimer->new('123456789abcdef123456789abcdef');

The validity of the API key is not checked here but using an invalid key will result in a failure to login() later.

login

Logs in to SlimTimer using the provided login and password.

$st->login('your@email.address', 'secret-password');

This method must be called before doing anything else with this object.

list_tasks

Returns the list of all tasks involving the logged in user:

my @tasks = $st->list_tasks();
say join("\n", map { $_->name } @tasks); # Output the names of all tasks

By default all tasks are returned, even the completed ones. Passing a false value as parameter excludes the completed tasks:

my @active_tasks = $st->list_tasks(0);

See WebService::SlimTimer::Task for the details of the returned objects.

create_task

Create a new task with the given name and returns the new WebService::SlimTimer::Task object on success.

my $task = $st->create_task('Test Task');
... Use $task->id with the other methods ...

delete_task

Delete the task with the given id (presumably previously obtained from list_tasks).

$st->delete_task($task->id);

get_task

Find the given task by its id.

my $task = $st->get_task(task_id);

While there is no direct way to obtain a task id using this module, it could be cached locally from a previous program execution, for example.

complete_task

Mark the task with the given id as being completed.

$st->complete_task($task->id, DateTime->now);

list_entries

Return all the time entries.

If the optional start and/or end parameters are specified, returns only the entries that begin after the start date and/or before the end one.

# List all entries: potentially very time-consuming.
my @entries = $st->list_entries;

# List entries started today.
my $today = DateTime->now;
$today->set(hour => 0, minute => 0, second => 0);
my @today_entries = $st->list_entries(start => $today);

# List entries started in 2010.
my @entries_2010 = $st->list_entries(
    start => DateTime->new(year => 2010),
    end => DateTime->new(year => 2011)
);

list_task_entries

Return all the time entries for the given task.

Just as list_entries, this method accepts optional start and end parameters to restrict the dates of the entries retrieved.

my @today_work_on_task = $st->list_entries($task->id, start => $today);

get_entry

Find the given time entry by its id.

my $entry = $st->get_entry($entry_id);

As with get_task(), it only makes sense to use this method if the id comes from a local cache.

create_entry

Create a new time entry.

my $day_of_work = $st->create_entry($task->id,
        DateTime->now->set(hour => 9, minute => 0, second = 0),
        DateTime->now->set(hour => 17, minute => 0, second = 0)
    );

Notice that the time stamps should normally be in UTC and not local time or another time zone.

If the end parameter is not specified, it defaults to now.

Returns the entry that was created.

update_entry

Changes an existing time entry.

# Use more realistic schedule.
$st->update_entry($day_of_work->id, $task->id,
        DateTime->now->set(hour => 11, minute => 0, second = 0)
        DateTime->now->set(hour => 23, minute => 0, second = 0)
    );

delete_entry

Deletes a time entry.

$st->delete_entry($day_of_work->id);

VARIABLES

This module define VERSION and DEBUG package variables. The first one is self-explanatory, the second one is 0 by default but can be set to 1 to trace all network requests done by this module. Setting it to 2 will also dump the requests (and replies) contents.

SEE ALSO

WebService::SlimTimer::Task, WebService::SlimTimer::TimeEntry

BUGS

Currently the offset parameter is not used by list_tasks and list_entries and list_task_entries methods, so they are limited to 50 tasks for the first one and 5000 entries for the latter two and accessing the subsequent results is impossible.

Access to the comments and tags of the tasks and time entries objects is not implemented yet.

AUTHOR

Vadim Zeitlin <vz-cpan@zeitlins.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2011 by Vadim Zeitlin.

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