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
|
|
|
|
|
|
|
|