File Coverage

blib/lib/WebService/Toggl/Report/Weekly.pm
Criterion Covered Total %
statement 12 13 92.3
branch n/a
condition n/a
subroutine 4 5 80.0
pod n/a
total 16 18 88.8


line stmt bran cond sub pod time code
1             package WebService::Toggl::Report::Weekly;
2              
3 1     1   1042 use Sub::Quote qw(quote_sub);
  1         2  
  1         46  
4 1     1   5 use Types::Standard qw(Enum);
  1         1  
  1         5  
5              
6 1     1   295 use Moo;
  1         2  
  1         5  
7             with 'WebService::Toggl::Role::Report';
8 1     1   346 use namespace::clean;
  1         2  
  1         4  
9              
10 0     0     sub api_path { 'weekly' }
11              
12             around _req_params => sub {
13             my $orig = shift;
14             my $self = shift;
15             return [ @{$self->$orig}, qw(grouping calculate) ];
16             };
17              
18             # request params
19             has grouping => (
20             is => 'ro',
21             isa => Enum[qw(users projects)],
22             default => 'projects',
23             );
24             has calculate => (
25             is => 'ro',
26             isa => Enum[qw(time earnings)],
27             default => 'time',
28             );
29              
30              
31             # repsonse params
32             # **none**
33              
34             has week_totals => (is => 'ro', lazy => 1, builder => quote_sub(qq| \$_[0]->raw->{week_totals} |));
35              
36             1;
37             __END__
38              
39              
40             =encoding utf-8
41              
42             =head1 NAME
43              
44             WebService::Toggl::Report::Weekly - Toggl weekly aggregated report object
45              
46             =head1 SYNOPSIS
47              
48             use WebService::Toggl;
49             my $toggl = WebService::Toggl->new({api_key => 'foo'});
50              
51             my $report = $toggl->weekly({
52             workspace_id => 1234,
53             grouping => 'projects', calculate => 'earnings',
54             });
55              
56             say $report->total_billable; # billable milliseconds
57             say $report->week_totals; # array of totals per day
58             for $project (@{ $report->data }) {
59             say "Project $project->{title}{project} earned "
60             . "$project->{amount}[7] $project->{currency} this week.";
61             for my $user ($projects->{details}) {
62             say " User $user->{title}{user} contributed "
63             . "$user->{amount}[7] $user->{currency} to that total";
64             }
65             }
66              
67             =head1 DESCRIPTION
68              
69             This module is a wrapper object around the Toggl weekly report
70             L<described here|https://github.com/toggl/toggl_api_docs/blob/master/reports/weekly.md>.
71             It returns a report of either time spent or earnings grouped by either
72             project or user.
73              
74             =head1 REQUEST ATTRIBUTES
75              
76             Request attributes common to all reports are detailed in the
77             L<::Role::Request|WebService::Toggl::Role::Report#REQUEST-ATTRIBUTES> pod.
78              
79             The C<until> attribute is ignored for the weekly report. It is always
80             assumed to be C<since> plus six days (for a total of seven).
81              
82             =head2 grouping
83              
84             Which metric to group reports by. Must be either C<projects> or
85             C<users>. Whichever is B<not> selected is used as the subgrouping
86             parameter.
87              
88             =head2 calculate
89              
90             The property to aggregate. Must be one of C<time> or C<earnings>.
91              
92             =head1 RESPONSE ATTRIBUTES
93              
94             Response attributes common to all reports are detailed in the
95             L<::Role::Request|WebService::Toggl::Role::Report#RESPONSE-ATTRIBUTES> pod.
96              
97             =head2 weekly_totals
98              
99             Eight-element array ref showing aggregated totals of the L</calculate>
100             property for each day, with a sum total as the last element.
101              
102             =head1 REPORT DATA
103              
104             The C<data> attribute of a C<::Report::Weekly> object is an arrayref
105             of hashrefs representing the L</grouping> property. It contains a
106             C<details> key with an array of hashrefs representing the subgrouping
107             parameter. If the L</calculate> property is C<time>, the C<data>
108             attribute will contain a C<totals> key with the daily time aggregates.
109             If L</calculate> is C<earnings> , it will contain a C<currency> key
110             and an C<amounts> key with the daily aggregated earnings. For more
111             details, see the L<Toggl API
112             docs|https://github.com/toggl/toggl_api_docs/blob/master/reports/weekly.md>.
113              
114             =head1 LICENSE
115              
116             Copyright (C) Fitz Elliott.
117              
118             This library is free software; you can redistribute it and/or modify
119             it under the same terms as Perl itself.
120              
121             =head1 AUTHOR
122              
123             Fitz Elliott E<lt>felliott@fiskur.orgE<gt>
124              
125             =cut
126