| line |
stmt |
bran |
cond |
sub |
pod |
time |
code |
|
1
|
|
|
|
|
|
|
package Protocol::Notifo; |
|
2
|
|
|
|
|
|
|
|
|
3
|
|
|
|
|
|
|
|
|
4
|
|
|
|
|
|
|
|
|
5
|
3
|
|
|
3
|
|
15
|
use strict; |
|
|
3
|
|
|
|
|
6
|
|
|
|
3
|
|
|
|
|
68
|
|
|
6
|
3
|
|
|
3
|
|
10
|
use warnings; |
|
|
3
|
|
|
|
|
4
|
|
|
|
3
|
|
|
|
|
95
|
|
|
7
|
3
|
|
|
3
|
|
11
|
use Carp 'confess'; |
|
|
3
|
|
|
|
|
3
|
|
|
|
3
|
|
|
|
|
128
|
|
|
8
|
3
|
|
|
3
|
|
716
|
use JSON 'decode_json'; |
|
|
3
|
|
|
|
|
32849
|
|
|
|
3
|
|
|
|
|
26
|
|
|
9
|
3
|
|
|
3
|
|
1428
|
use MIME::Base64 'encode_base64'; |
|
|
3
|
|
|
|
|
1846
|
|
|
|
3
|
|
|
|
|
192
|
|
|
10
|
3
|
|
|
3
|
|
738
|
use File::HomeDir; |
|
|
3
|
|
|
|
|
37832
|
|
|
|
3
|
|
|
|
|
211
|
|
|
11
|
3
|
|
|
3
|
|
749
|
use File::Spec::Functions qw( catfile ); |
|
|
3
|
|
|
|
|
1762
|
|
|
|
3
|
|
|
|
|
200
|
|
|
12
|
3
|
|
|
3
|
|
736
|
use namespace::clean; |
|
|
3
|
|
|
|
|
55646
|
|
|
|
3
|
|
|
|
|
30
|
|
|
13
|
|
|
|
|
|
|
|
|
14
|
|
|
|
|
|
|
=constructor new |
|
15
|
|
|
|
|
|
|
|
|
16
|
|
|
|
|
|
|
Creates new C<Protocol::Notifo> object. |
|
17
|
|
|
|
|
|
|
|
|
18
|
|
|
|
|
|
|
It first tries to load default values from a configuration file. If you |
|
19
|
|
|
|
|
|
|
set the environment variable C<NOTIFO_CFG>, it will try that. If not, it |
|
20
|
|
|
|
|
|
|
will default to L<File::HomeDir/my_home|File::HomeDir->my_home()>. See |
|
21
|
|
|
|
|
|
|
L<CONFIGURATION FILE> for the format of the file. |
|
22
|
|
|
|
|
|
|
|
|
23
|
|
|
|
|
|
|
You can also pass a hash of options, that will override the |
|
24
|
|
|
|
|
|
|
configuration file. The following options are accepted: |
|
25
|
|
|
|
|
|
|
|
|
26
|
|
|
|
|
|
|
=over 4 |
|
27
|
|
|
|
|
|
|
|
|
28
|
|
|
|
|
|
|
=item user |
|
29
|
|
|
|
|
|
|
|
|
30
|
|
|
|
|
|
|
The API username. |
|
31
|
|
|
|
|
|
|
|
|
32
|
|
|
|
|
|
|
=item api_key |
|
33
|
|
|
|
|
|
|
|
|
34
|
|
|
|
|
|
|
The API key. |
|
35
|
|
|
|
|
|
|
|
|
36
|
|
|
|
|
|
|
=back |
|
37
|
|
|
|
|
|
|
|
|
38
|
|
|
|
|
|
|
Values for this two options can be found in the |
|
39
|
|
|
|
|
|
|
L<http://notifo.com/user/settings|user settings page> of |
|
40
|
|
|
|
|
|
|
L<http://notifo.com/|Notifo site>. |
|
41
|
|
|
|
|
|
|
|
|
42
|
|
|
|
|
|
|
=cut |
|
43
|
|
|
|
|
|
|
sub new { |
|
44
|
7
|
|
|
7
|
0
|
25
|
my ($class, %args) = @_; |
|
45
|
7
|
|
|
|
|
17
|
my $self = bless $class->_read_config_file, $class; |
|
46
|
|
|
|
|
|
|
|
|
47
|
7
|
|
|
|
|
25
|
for my $f (qw( user api_key )) { |
|
48
|
13
|
100
|
|
|
|
37
|
$self->{$f} = $args{$f} if exists $args{$f}; |
|
49
|
13
|
100
|
|
|
|
55
|
confess("Missing required parameter '$f' to new(), ") unless $self->{$f}; |
|
50
|
|
|
|
|
|
|
} |
|
51
|
|
|
|
|
|
|
|
|
52
|
5
|
|
|
|
|
12
|
$self->{base_url} = 'https://api.notifo.com/v1'; |
|
53
|
5
|
|
|
|
|
51
|
$self->{auth_hdr} = encode_base64(join(':', @$self{qw(user api_key)}), ''); |
|
54
|
|
|
|
|
|
|
|
|
55
|
5
|
|
|
|
|
55
|
return $self; |
|
56
|
|
|
|
|
|
|
} |
|
57
|
|
|
|
|
|
|
|
|
58
|
|
|
|
|
|
|
|
|
59
|
|
|
|
|
|
|
=method parse_response |
|
60
|
|
|
|
|
|
|
|
|
61
|
|
|
|
|
|
|
Accepts two parameters, a HTTP response code and the response content. |
|
62
|
|
|
|
|
|
|
It parses the content, adds the HTTP response code and returns a hashref |
|
63
|
|
|
|
|
|
|
with all the fields. |
|
64
|
|
|
|
|
|
|
|
|
65
|
|
|
|
|
|
|
The following fields are present on all responses: |
|
66
|
|
|
|
|
|
|
|
|
67
|
|
|
|
|
|
|
=over 4 |
|
68
|
|
|
|
|
|
|
|
|
69
|
|
|
|
|
|
|
=item status |
|
70
|
|
|
|
|
|
|
|
|
71
|
|
|
|
|
|
|
A string, either C<success> or C<error>. |
|
72
|
|
|
|
|
|
|
|
|
73
|
|
|
|
|
|
|
=item http_code |
|
74
|
|
|
|
|
|
|
|
|
75
|
|
|
|
|
|
|
The HTTP code of the response. |
|
76
|
|
|
|
|
|
|
|
|
77
|
|
|
|
|
|
|
=item response_code |
|
78
|
|
|
|
|
|
|
|
|
79
|
|
|
|
|
|
|
A Notifo.com integer response code. |
|
80
|
|
|
|
|
|
|
|
|
81
|
|
|
|
|
|
|
=item response_message |
|
82
|
|
|
|
|
|
|
|
|
83
|
|
|
|
|
|
|
A text description of the response. Specially useful with |
|
84
|
|
|
|
|
|
|
C<status> C<error>. |
|
85
|
|
|
|
|
|
|
|
|
86
|
|
|
|
|
|
|
=back |
|
87
|
|
|
|
|
|
|
|
|
88
|
|
|
|
|
|
|
=cut |
|
89
|
|
|
|
|
|
|
sub parse_response { |
|
90
|
3
|
|
|
3
|
0
|
7
|
my ($self, $http_code, $content) = @_; |
|
91
|
|
|
|
|
|
|
|
|
92
|
3
|
|
|
|
|
56
|
my $res = decode_json($content); |
|
93
|
3
|
|
|
|
|
5
|
$res->{http_code} = $http_code; |
|
94
|
|
|
|
|
|
|
|
|
95
|
3
|
|
|
|
|
28
|
return $res; |
|
96
|
|
|
|
|
|
|
} |
|
97
|
|
|
|
|
|
|
|
|
98
|
|
|
|
|
|
|
|
|
99
|
|
|
|
|
|
|
=method send_notification |
|
100
|
|
|
|
|
|
|
|
|
101
|
|
|
|
|
|
|
Prepares a request for the C<send_notification> API. |
|
102
|
|
|
|
|
|
|
|
|
103
|
|
|
|
|
|
|
Accepts a hash with options. The following options are supported: |
|
104
|
|
|
|
|
|
|
|
|
105
|
|
|
|
|
|
|
=over 4 |
|
106
|
|
|
|
|
|
|
|
|
107
|
|
|
|
|
|
|
=item msg |
|
108
|
|
|
|
|
|
|
|
|
109
|
|
|
|
|
|
|
The notification message. This parameter is B<required>. |
|
110
|
|
|
|
|
|
|
|
|
111
|
|
|
|
|
|
|
=item to |
|
112
|
|
|
|
|
|
|
|
|
113
|
|
|
|
|
|
|
The destination user. If the API username/key pair used is of a User |
|
114
|
|
|
|
|
|
|
account, then this parameter is ignored and can be safelly ommited. |
|
115
|
|
|
|
|
|
|
|
|
116
|
|
|
|
|
|
|
A User account can only send notifications to itself. A Service account |
|
117
|
|
|
|
|
|
|
can send notifications to all his subscribed users. |
|
118
|
|
|
|
|
|
|
|
|
119
|
|
|
|
|
|
|
=item label |
|
120
|
|
|
|
|
|
|
|
|
121
|
|
|
|
|
|
|
A label describing the application that is sending the |
|
122
|
|
|
|
|
|
|
notification. With Service accounts, this option is ignored and the |
|
123
|
|
|
|
|
|
|
Service Name is used. |
|
124
|
|
|
|
|
|
|
|
|
125
|
|
|
|
|
|
|
=item title |
|
126
|
|
|
|
|
|
|
|
|
127
|
|
|
|
|
|
|
The title or subject of the notification. |
|
128
|
|
|
|
|
|
|
|
|
129
|
|
|
|
|
|
|
=item uri |
|
130
|
|
|
|
|
|
|
|
|
131
|
|
|
|
|
|
|
The URL for the event. On some clients you can click the notification and jump to this URL. |
|
132
|
|
|
|
|
|
|
|
|
133
|
|
|
|
|
|
|
=back |
|
134
|
|
|
|
|
|
|
|
|
135
|
|
|
|
|
|
|
The return value is a hashref with all the relevant information to |
|
136
|
|
|
|
|
|
|
perform the HTTP request: the url and the method to use, the |
|
137
|
|
|
|
|
|
|
Authorization header, and the query form fields. |
|
138
|
|
|
|
|
|
|
|
|
139
|
|
|
|
|
|
|
An example: |
|
140
|
|
|
|
|
|
|
|
|
141
|
|
|
|
|
|
|
url => "https://api.notifo.com/v1/send_notification", |
|
142
|
|
|
|
|
|
|
method => "POST", |
|
143
|
|
|
|
|
|
|
args => { |
|
144
|
|
|
|
|
|
|
label => "my application", |
|
145
|
|
|
|
|
|
|
msg => "hello there!", |
|
146
|
|
|
|
|
|
|
title => "welcome", |
|
147
|
|
|
|
|
|
|
to => "user_x", |
|
148
|
|
|
|
|
|
|
uri => "http://www.example.com/welcome/" |
|
149
|
|
|
|
|
|
|
}, |
|
150
|
|
|
|
|
|
|
headers => { |
|
151
|
|
|
|
|
|
|
Authorization => "bWU6bXlfa2V5" |
|
152
|
|
|
|
|
|
|
}, |
|
153
|
|
|
|
|
|
|
|
|
154
|
|
|
|
|
|
|
The following keys are always present in the hashref: |
|
155
|
|
|
|
|
|
|
|
|
156
|
|
|
|
|
|
|
=over 4 |
|
157
|
|
|
|
|
|
|
|
|
158
|
|
|
|
|
|
|
=item url |
|
159
|
|
|
|
|
|
|
|
|
160
|
|
|
|
|
|
|
The URL where the HTTP request should be sent to. |
|
161
|
|
|
|
|
|
|
|
|
162
|
|
|
|
|
|
|
=item method |
|
163
|
|
|
|
|
|
|
|
|
164
|
|
|
|
|
|
|
The HTTP method to use. |
|
165
|
|
|
|
|
|
|
|
|
166
|
|
|
|
|
|
|
=item args |
|
167
|
|
|
|
|
|
|
|
|
168
|
|
|
|
|
|
|
A hashref with all the URL query form fields and values. |
|
169
|
|
|
|
|
|
|
|
|
170
|
|
|
|
|
|
|
=item headers |
|
171
|
|
|
|
|
|
|
|
|
172
|
|
|
|
|
|
|
A hashref with all the headers to include in the HTTP request. |
|
173
|
|
|
|
|
|
|
|
|
174
|
|
|
|
|
|
|
=back |
|
175
|
|
|
|
|
|
|
|
|
176
|
|
|
|
|
|
|
=cut |
|
177
|
|
|
|
|
|
|
sub send_notification { |
|
178
|
7
|
|
|
7
|
0
|
27
|
my ($self, %args) = @_; |
|
179
|
|
|
|
|
|
|
|
|
180
|
7
|
|
|
|
|
55
|
my %call = ( |
|
181
|
|
|
|
|
|
|
url => "$self->{base_url}/send_notification", |
|
182
|
|
|
|
|
|
|
method => 'POST', |
|
183
|
|
|
|
|
|
|
headers => {Authorization => $self->{auth_hdr}}, |
|
184
|
|
|
|
|
|
|
args => {}, |
|
185
|
|
|
|
|
|
|
); |
|
186
|
|
|
|
|
|
|
|
|
187
|
7
|
|
|
|
|
25
|
for my $f (qw( to msg label title uri )) { |
|
188
|
35
|
|
|
|
|
37
|
my $v = $args{$f}; |
|
189
|
35
|
100
|
|
|
|
52
|
next unless defined $v; |
|
190
|
|
|
|
|
|
|
|
|
191
|
16
|
|
|
|
|
28
|
$call{args}{$f} = $v; |
|
192
|
|
|
|
|
|
|
} |
|
193
|
|
|
|
|
|
|
|
|
194
|
7
|
100
|
|
|
|
25
|
confess("Missing required argument 'msg', ") unless $call{args}{msg}; |
|
195
|
|
|
|
|
|
|
|
|
196
|
6
|
|
|
|
|
62
|
return \%call; |
|
197
|
|
|
|
|
|
|
} |
|
198
|
|
|
|
|
|
|
|
|
199
|
|
|
|
|
|
|
=method config_file |
|
200
|
|
|
|
|
|
|
|
|
201
|
|
|
|
|
|
|
Returns the configuration file that this module will attempt to use. |
|
202
|
|
|
|
|
|
|
|
|
203
|
|
|
|
|
|
|
=cut |
|
204
|
|
|
|
|
|
|
sub config_file { |
|
205
|
10
|
|
|
10
|
0
|
16
|
my ($self) = @_; |
|
206
|
|
|
|
|
|
|
|
|
207
|
10
|
|
66
|
|
|
115
|
return $ENV{NOTIFO_CFG} || catfile(File::HomeDir->my_home, '.notifo.rc'); |
|
208
|
|
|
|
|
|
|
} |
|
209
|
|
|
|
|
|
|
|
|
210
|
|
|
|
|
|
|
|
|
211
|
|
|
|
|
|
|
=head1 CONFIGURATION FILE |
|
212
|
|
|
|
|
|
|
|
|
213
|
|
|
|
|
|
|
The configuration file is line based. Empty lines os just spaces/tabs, |
|
214
|
|
|
|
|
|
|
or lines starting with # are ignored. |
|
215
|
|
|
|
|
|
|
|
|
216
|
|
|
|
|
|
|
All other lines are parsed for commands, in the form |
|
217
|
|
|
|
|
|
|
C<command separator value>. The C<separator> can be a C<=> or a C<:>. |
|
218
|
|
|
|
|
|
|
|
|
219
|
|
|
|
|
|
|
See the L<CONSTRUCTORS|new() constructor> for the commands you can use, |
|
220
|
|
|
|
|
|
|
they are the same ones as the accepted options. |
|
221
|
|
|
|
|
|
|
|
|
222
|
|
|
|
|
|
|
=cut |
|
223
|
|
|
|
|
|
|
sub _read_config_file { |
|
224
|
7
|
|
|
7
|
|
13
|
my ($self) = @_; |
|
225
|
7
|
|
|
|
|
9
|
my %opts; |
|
226
|
|
|
|
|
|
|
|
|
227
|
7
|
|
|
|
|
16
|
my $fn = $self->config_file; |
|
228
|
7
|
100
|
|
|
|
472
|
return \%opts unless -r $fn; |
|
229
|
|
|
|
|
|
|
|
|
230
|
2
|
50
|
|
|
|
99
|
open(my $fh, '<', $fn) || confess("Could not open file '$fn': $!, "); |
|
231
|
|
|
|
|
|
|
|
|
232
|
2
|
|
|
|
|
57
|
while (my $l = <$fh>) { |
|
233
|
16
|
|
|
|
|
18
|
chomp($l); |
|
234
|
16
|
|
|
|
|
113
|
$l =~ s/^\s*(#.*)?|\s*$//g; |
|
235
|
16
|
100
|
|
|
|
44
|
next unless $l; |
|
236
|
|
|
|
|
|
|
|
|
237
|
6
|
|
|
|
|
29
|
my ($k, $v) = $l =~ m/(\S+)\s*[=:]\s*(.*)/; |
|
238
|
6
|
50
|
|
|
|
15
|
confess("Could not parse line $. of $fn ('$l'), ") unless $k; |
|
239
|
|
|
|
|
|
|
|
|
240
|
6
|
|
|
|
|
31
|
$opts{$k} = $v; |
|
241
|
|
|
|
|
|
|
} |
|
242
|
|
|
|
|
|
|
|
|
243
|
2
|
|
|
|
|
59
|
return \%opts; |
|
244
|
|
|
|
|
|
|
} |
|
245
|
|
|
|
|
|
|
|
|
246
|
|
|
|
|
|
|
1; |
|
247
|
|
|
|
|
|
|
|
|
248
|
|
|
|
|
|
|
__END__ |
|
249
|
|
|
|
|
|
|
|
|
250
|
|
|
|
|
|
|
=head1 SYNOPSIS |
|
251
|
|
|
|
|
|
|
|
|
252
|
|
|
|
|
|
|
## Reads user and api_key from configuration file |
|
253
|
|
|
|
|
|
|
my $pn = Protocol::Notifo->new; |
|
254
|
|
|
|
|
|
|
|
|
255
|
|
|
|
|
|
|
## Use a particular user and api_key, overrides configuration file |
|
256
|
|
|
|
|
|
|
my $pn = Protocol::Notifo->new(user => 'me', api_key => 'my_key'); |
|
257
|
|
|
|
|
|
|
|
|
258
|
|
|
|
|
|
|
my $req = $pn->send_notification(msg => 'Hi!'); |
|
259
|
|
|
|
|
|
|
|
|
260
|
|
|
|
|
|
|
.... send $req, get a response back .... |
|
261
|
|
|
|
|
|
|
|
|
262
|
|
|
|
|
|
|
my $res = $pn->parse_response($response_http_code, $response_body); |
|
263
|
|
|
|
|
|
|
|
|
264
|
|
|
|
|
|
|
.... do stuff with $res .... |
|
265
|
|
|
|
|
|
|
|
|
266
|
|
|
|
|
|
|
|
|
267
|
|
|
|
|
|
|
=head1 DESCRIPTION |
|
268
|
|
|
|
|
|
|
|
|
269
|
|
|
|
|
|
|
This module provides a API to prepare requests to the |
|
270
|
|
|
|
|
|
|
L<http://api.notifo.com/|notifo.com API>. |
|
271
|
|
|
|
|
|
|
|
|
272
|
|
|
|
|
|
|
The module doesn't actually execute a HTTP request. It only prepares |
|
273
|
|
|
|
|
|
|
all the information required for such request to be performed. As such |
|
274
|
|
|
|
|
|
|
this module is not to be used by end users, but by writters of the |
|
275
|
|
|
|
|
|
|
Notifo.com API. |
|
276
|
|
|
|
|
|
|
|
|
277
|
|
|
|
|
|
|
If you are an end-user and want to call the API, you should look into |
|
278
|
|
|
|
|
|
|
the modules L<WebService::Notifo> and L<AnyEvent::WebService::Notifo>. |
|
279
|
|
|
|
|
|
|
|
|
280
|
|
|
|
|
|
|
This module supports both the User API and the Service API. |
|
281
|
|
|
|
|
|
|
Differences between the behaviour of the two are noted in this |
|
282
|
|
|
|
|
|
|
documentation where relevant. |
|
283
|
|
|
|
|
|
|
|
|
284
|
|
|
|
|
|
|
You need a Notifo.com account to be able to use this module. The account |
|
285
|
|
|
|
|
|
|
will give you access to a API username, and a API key. Both are required |
|
286
|
|
|
|
|
|
|
arguments of our L</CONSTRUCTORS|constructors>. |
|
287
|
|
|
|
|
|
|
|
|
288
|
|
|
|
|
|
|
The module also supports a configuration file. See |
|
289
|
|
|
|
|
|
|
L</config_file|config_file()> to learn which configuration files are |
|
290
|
|
|
|
|
|
|
loaded automatically, if found. |
|
291
|
|
|
|
|
|
|
|
|
292
|
|
|
|
|
|
|
For all the details of this API, check out the site |
|
293
|
|
|
|
|
|
|
L<http://api.notifo.com/|http://api.notifo.com/>. |
|
294
|
|
|
|
|
|
|
|
|
295
|
|
|
|
|
|
|
|
|
296
|
|
|
|
|
|
|
=head1 TODO |
|
297
|
|
|
|
|
|
|
|
|
298
|
|
|
|
|
|
|
Future versions of this module will implement the other APIs: |
|
299
|
|
|
|
|
|
|
|
|
300
|
|
|
|
|
|
|
=over 4 |
|
301
|
|
|
|
|
|
|
|
|
302
|
|
|
|
|
|
|
=item subscribe_user |
|
303
|
|
|
|
|
|
|
|
|
304
|
|
|
|
|
|
|
=item send_message |
|
305
|
|
|
|
|
|
|
|
|
306
|
|
|
|
|
|
|
=back |
|
307
|
|
|
|
|
|
|
|
|
308
|
|
|
|
|
|
|
Patches welcome. |
|
309
|
|
|
|
|
|
|
|
|
310
|
|
|
|
|
|
|
|
|
311
|
|
|
|
|
|
|
=cut |
|
312
|
|
|
|
|
|
|
|