LP#1673870: indicate suspended holds for OverDrive
[working/Evergreen.git] / Open-ILS / src / perlmods / lib / OpenILS / Application / EbookAPI / OverDrive.pm
1 #!/usr/bin/perl
2
3 # Copyright (C) 2015 BC Libraries Cooperative
4 #
5 # This program is free software; you can redistribute it and/or
6 # modify it under the terms of the GNU General Public License
7 # as published by the Free Software Foundation; either version 2
8 # of the License, or (at your option) any later version.
9
10 # This program is distributed in the hope that it will be useful,
11 # but WITHOUT ANY WARRANTY; without even the implied warranty of
12 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
13 # GNU General Public License for more details.
14
15 # You should have received a copy of the GNU General Public License
16 # along with this program; if not, write to the Free Software
17 # Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
18
19 package OpenILS::Application::EbookAPI::OverDrive;
20
21 use strict;
22 use warnings;
23
24 use OpenILS::Application;
25 use OpenILS::Application::EbookAPI;
26 use base qw/OpenILS::Application::EbookAPI/;
27 use OpenSRF::AppSession;
28 use OpenSRF::EX qw(:try);
29 use OpenSRF::Utils::SettingsClient;
30 use OpenSRF::Utils::Logger qw($logger);
31 use OpenSRF::Utils::Cache;
32 use OpenSRF::Utils::JSON;
33 use OpenILS::Application::AppUtils;
34 use Data::Dumper;
35
36 sub new {
37     my( $class, $args ) = @_;
38     $class = ref $class || $class;
39     return bless $args, $class;
40 }
41
42 sub ou {
43     my $self = shift;
44     return $self->{ou};
45 }
46
47 sub vendor {
48     my $self = shift;
49     return $self->{vendor};
50 }
51
52 sub session_id {
53     my $self = shift;
54     return $self->{session_id};
55 }
56
57 sub account_id {
58     my $self = shift;
59     return $self->{account_id};
60 }
61
62 sub websiteid {
63     my $self = shift;
64     return $self->{websiteid};
65 }
66
67 sub authorizationname {
68     my $self = shift;
69     return $self->{authorizationname};
70 }
71
72 sub basic_token {
73     my $self = shift;
74     return $self->{basic_token};
75 }
76
77 sub bearer_token {
78     my $self = shift;
79     return $self->{bearer_token};
80 }
81
82 sub collection_token {
83     my $self = shift;
84     return $self->{collection_token};
85 }
86
87 sub granted_auth_uri {
88     my $self = shift;
89     return $self->{granted_auth_uri};
90 }
91
92 sub password_required {
93     my $self = shift;
94     return $self->{password_required};
95 }
96
97 sub patron_token {
98     my $self = shift;
99     return $self->{patron_token};
100 }
101
102 sub initialize {
103     my $self = shift;
104     my $ou = $self->{ou};
105
106     my $discovery_base_uri = OpenILS::Application::AppUtils->ou_ancestor_setting_value($ou, 'ebook_api.overdrive.discovery_base_uri');
107     $self->{discovery_base_uri} = $discovery_base_uri || 'https://api.overdrive.com/v1';
108     my $circulation_base_uri = OpenILS::Application::AppUtils->ou_ancestor_setting_value($ou, 'ebook_api.overdrive.circulation_base_uri');
109     $self->{circulation_base_uri} = $circulation_base_uri || 'https://patron.api.overdrive.com/v1';
110
111     my $account_id = OpenILS::Application::AppUtils->ou_ancestor_setting_value($ou, 'ebook_api.overdrive.account_id');
112     if ($account_id) {
113         $self->{account_id} = $account_id;
114     } else {
115         $logger->error("EbookAPI: no OverDrive account ID found for org unit $ou");
116         return;
117     }
118
119     my $websiteid = OpenILS::Application::AppUtils->ou_ancestor_setting_value($ou, 'ebook_api.overdrive.websiteid');
120     if ($websiteid) {
121         $self->{websiteid} = $websiteid;
122     } else {
123         $logger->error("EbookAPI: no OverDrive website ID found for org unit $ou");
124         return;
125     }
126
127     my $authorizationname = OpenILS::Application::AppUtils->ou_ancestor_setting_value($ou, 'ebook_api.overdrive.authorizationname');
128     if ($authorizationname) {
129         $self->{authorizationname} = $authorizationname;
130     } else {
131         $logger->error("EbookAPI: no OverDrive authorization name found for org unit $ou");
132         return;
133     }
134
135     my $basic_token = OpenILS::Application::AppUtils->ou_ancestor_setting_value($ou, 'ebook_api.overdrive.basic_token');
136     if ($basic_token) {
137         $self->{basic_token} = $basic_token;
138     } else {
139         $logger->error("EbookAPI: no OverDrive basic token found for org unit $ou");
140         return;
141     }
142
143     my $granted_auth_uri = OpenILS::Application::AppUtils->ou_ancestor_setting_value($ou, 'ebook_api.overdrive.granted_auth_redirect_uri');
144     if ($granted_auth_uri) {
145         $self->{granted_auth_uri} = $granted_auth_uri;
146     }
147
148     my $password_required = OpenILS::Application::AppUtils->ou_ancestor_setting_value($ou, 'ebook_api.overdrive.password_required') || 0;
149     $self->{password_required} = $password_required;
150
151     return $self;
152
153 }
154
155 # Wrapper method for HTTP requests.
156 sub handle_http_request {
157     my $self = shift;
158     my $req = shift;
159
160     # Prep our request using defaults.
161     $req->{method} = 'GET' if (!$req->{method});
162     $req = $self->set_http_headers($req);
163
164     # Send the request.
165     my $res = $self->request($req, $self->{session_id});
166
167     $logger->info("EbookAPI: raw OverDrive HTTP response: " . Dumper $res);
168
169     # A "401 Unauthorized" response means we need to re-auth our client or patron.
170     if (defined ($res) && $res->{status} =~ /^401/) {
171         $logger->info("EbookAPI: 401 response received from OverDrive, re-authorizing...");
172
173         # Always re-auth client to ensure we have an up-to-date client token.
174         $self->do_client_auth();
175
176         # If we're using a Circulation API, redo patron auth too.
177         my $circulation_base_uri = $self->{circulation_base_uri};
178         if ($req->{uri} =~ /^$circulation_base_uri/) {
179             $self->do_patron_auth();
180         }
181
182         # Now we can update our headers with our fresh client/patron tokens
183         # and re-send our request.
184         $req = $self->set_http_headers($req);
185         return $self->request($req, $self->{session_id});
186     }
187
188     # For any non-401 response (including no response at all),
189     # just return whatever response we got (if any).
190     return $res;
191 }
192
193 # Set the correct headers for our request.
194 # Authorization headers are determined by which API we're using:
195 # - Circulation APIs use a patron access token.
196 # - Discovery APIs use a regular access token.
197 # - For other APIs, fallback to our basic token.
198 sub set_http_headers {
199     my $self = shift;
200     my $req = shift;
201     $req->{headers} = {} if (!$req->{headers});
202     if (!$req->{headers}->{Authorization}) {
203         my $auth_type;
204         my $token;
205         my $circulation_base_uri = $self->{circulation_base_uri};
206         my $discovery_base_uri = $self->{discovery_base_uri};
207         if ($req->{uri} =~ /^$circulation_base_uri/) {
208             $auth_type = 'Bearer';
209             $token = $self->{patron_token};
210         } elsif ($req->{uri} =~ /^$discovery_base_uri/) {
211             $auth_type = 'Bearer';
212             $token = $self->{bearer_token};
213         } else {
214             $auth_type = 'Basic';
215             $token = $self->{basic_token};
216         }
217         if (!$token) {
218             $logger->error("EbookAPI: unable to set HTTP Authorization header without token");
219             $logger->error("EbookAPI: failed request: " . Dumper $req);
220             return;
221         } else {
222             $req->{headers}->{Authorization} = "$auth_type $token";
223         }
224     }
225     return $req;
226 }
227
228 # POST /token HTTP/1.1
229 # Host: oauth.overdrive.com
230 # Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW
231
232 # grant_type=client_credentials
233 sub do_client_auth {
234     my $self = shift;
235     my $req = {
236         method  => 'POST',
237         uri     => 'https://oauth.overdrive.com/token',
238         headers => {
239             'Authorization' => 'Basic ' . $self->{basic_token},
240             'Content-Type'  => 'application/x-www-form-urlencoded;charset=UTF-8'
241         },
242         content => 'grant_type=client_credentials'
243     };
244     my $res = $self->request($req, $self->{session_id});
245
246     if (defined ($res)) {
247         if ($res->{content}->{access_token}) {
248             # save our access token for future use
249             $self->{bearer_token} = $res->{content}->{access_token};
250             # use access token to grab other library info (e.g. collection token)
251             $self->get_library_info();
252             return $res;
253         } else {
254             $logger->error("EbookAPI: bearer token not received from OverDrive API");
255             $logger->error("EbookAPI: bad response: " . Dumper $res);
256         }
257     } else {
258         $logger->error("EbookAPI: no client authentication response from OverDrive API");
259     }
260     return;
261 }
262
263 sub do_patron_auth {
264     my $self = shift;
265     my @args = @_;
266     if ($self->{granted_auth_uri}) {
267         return $self->do_granted_patron_auth(@args);
268     } else {
269         return $self->do_basic_patron_auth(@args);
270     }
271 }
272
273 # TODO
274 sub do_granted_patron_auth {
275 }
276
277 # POST /patrontoken HTTP/1.1
278 # Host: oauth-patron.overdrive.com
279 # Authorization: Basic {Base64-encoded string}
280 # Content-Type: application/x-www-form-urlencoded;charset=UTF-8
281
282 # grant_type=password&username=1234567890&password=1234&scope=websiteid:12345 authorizationname:default
283 # OR:
284 # grant_type=password&username=1234567890&password=[ignore]&password_required=false&scope=websiteid:12345 authorizationname:default
285 sub do_basic_patron_auth {
286     my $self = shift;
287     my $barcode = shift;
288
289     if ($barcode) {
290         if (!$self->{patron_barcode}) {
291             $self->{patron_barcode} = $barcode;
292         } elsif ($barcode ne $self->{patron_barcode}) {
293             $logger->error("EbookAPI: patron barcode in auth request does not match patron barcode for this session");
294             return;
295         }
296     } else {
297         if (!$self->{patron_barcode}) {
298             $logger->error("EbookAPI: Cannot authenticate patron with unknown barcode");
299         } else {
300             $barcode = $self->{patron_barcode};
301         }
302     }
303
304     # TODO handle cached/expired tokens?
305     # Making a request using an expired token will give a 401 Unauthorized error.
306     # Handle this appropriately.
307
308     # request content is an ugly url-encoded string
309     my $pw = (defined $self->{patron_password}) ? $self->{patron_password} : '';
310     my $content = 'grant_type=password';
311     $content .= "&username=$barcode";
312     if ($self->{password_required}) {
313         $content .= "&password=$pw";
314     } else {
315         $content .= '&password=xxx&password_required=false'
316     }
317     $content .= '&scope=websiteid:' . $self->{websiteid} . ' authorizationname:' . $self->{authorizationname};
318
319     my $req = {
320         method  => 'POST',
321         uri     => 'https://oauth-patron.overdrive.com/patrontoken',
322         headers => {
323             'Authorization' => 'Basic ' . $self->{basic_token},
324             'Content-Type'  => 'application/x-www-form-urlencoded;charset=UTF-8'
325         },
326         content => $content
327     };
328     my $res = $self->request($req, $self->{session_id});
329
330     if (defined ($res)) {
331         if ($res->{content}->{access_token}) {
332             $self->{patron_token} = $res->{content}->{access_token};
333             return $self->{patron_token};
334         } else {
335             $logger->error("EbookAPI: patron access token not received from OverDrive API");
336         }
337     } else {
338         $logger->error("EbookAPI: no patron authentication response from OverDrive API");
339     }
340     return;
341 }
342
343 # GET http://api.overdrive.com/v1/libraries/1225
344 # User-Agent: {Your application}
345 # Authorization: Bearer {OAuth access token}
346 # Host: api.overdrive.com
347 sub get_library_info {
348     my $self = shift;
349     my $library_id = $self->{account_id};
350     my $req = {
351         method  => 'GET',
352         uri     => $self->{discovery_base_uri} . "/libraries/$library_id"
353     };
354     if (my $res = $self->handle_http_request($req, $self->{session_id})) {
355         $self->{collection_token} = $res->{content}->{collectionToken};
356         return $self->{collection_token};
357     } else {
358         $logger->error("EbookAPI: OverDrive Library Account API request failed");
359         return;
360     }
361 }
362
363 # GET http://api.overdrive.com/v1/collections/v1L1BYwAAAA2Q/products/76c1b7d0-17f4-4c05-8397-c66c17411584/metadata
364 # User-Agent: {Your application}
365 # Authorization: Bearer {OAuth access token}
366 # Host: api.overdrive.com
367 sub get_title_info {
368     my $self = shift;
369     my $title_id = shift;
370     $self->do_client_auth() if (!$self->{bearer_token});
371     $self->get_library_info() if (!$self->{collection_token});
372     my $collection_token = $self->{collection_token};
373     my $req = {
374         method  => 'GET',
375         uri     => $self->{discovery_base_uri} . "/collections/$collection_token/products/$title_id/metadata"
376     };
377     if (my $res = $self->handle_http_request($req, $self->{session_id})) {
378         if ($res->{content}->{title}) {
379             my $info = {
380                 title  => $res->{content}->{title},
381                 author => $res->{content}->{creators}[0]{name}
382             };
383             # Append format information (useful for checkouts).
384             $info->{formats} = $self->get_formats($title_id);
385             return $info;
386         } else {
387             $logger->error("EbookAPI: OverDrive metadata lookup failed for $title_id");
388         }
389     } else {
390         $logger->error("EbookAPI: no metadata response from OverDrive API");
391     }
392     return;
393 }
394
395 # GET http://api.overdrive.com/v1/collections/L1BAAEAAA2i/products/76C1B7D0-17F4-4C05-8397-C66C17411584/availability
396 # User-Agent: {Your application}
397 # Authorization: Bearer {OAuth access token}
398 # Host: api.overdrive.com
399 sub do_availability_lookup {
400     my $self = shift;
401     my $title_id = shift;
402     $self->do_client_auth() if (!$self->{bearer_token});
403     $self->get_library_info() if (!$self->{collection_token});
404     my $req = {
405         method  => 'GET',
406         uri     => $self->{discovery_base_uri} . "/collections/" . $self->{collection_token} . "/products/$title_id/availability"
407     };
408     if (my $res = $self->handle_http_request($req, $self->{session_id})) {
409         return $res->{content}->{available};
410     } else {
411         $logger->error("EbookAPI: could not retrieve OverDrive availability for title $title_id");
412         return;
413     }
414 }
415
416 # Holdings lookup has two parts:
417 #
418 # 1. Copy availability: as above, but grab more details.
419 #
420 # 2. Formats:
421 #     GET https://api.overdrive.com/v1/collections/v1L1BYwAAAA2Q/products/76c1b7d0-17f4-4c05-8397-c66c17411584/metadata
422 #     User-Agent: {Your application}
423 #     Authorization: Bearer {OAuth access token}
424 #     Host: api.overdrive.com
425 #
426 sub do_holdings_lookup {
427     my ($self, $title_id) = @_;
428     $self->do_client_auth() if (!$self->{bearer_token});
429     $self->get_library_info() if (!$self->{collection_token});
430     my $collection_token = $self->{collection_token};
431
432     # prepare data structure to be used as return value
433     my $holdings = {
434         copies_owned => 0,
435         copies_available => 0,
436         formats => []
437     };
438
439     # request copy availability totals
440     my $avail_req = {
441         method  => 'GET',
442         uri     => $self->{discovery_base_uri} . "/collections/$collection_token/products/$title_id/availability"
443     };
444     if (my $avail_res = $self->handle_http_request($avail_req, $self->{session_id})) {
445         $holdings->{copies_owned} = $avail_res->{content}->{copiesOwned};
446         $holdings->{copies_available} = $avail_res->{content}->{copiesAvailable};
447     } else {
448         $logger->error("EbookAPI: failed to retrieve OverDrive holdings counts for title $title_id");
449     }
450
451     # request available formats
452     $holdings->{formats} = $self->get_formats($title_id);
453
454     return $holdings;
455 }
456
457 # Returns a list of available formats for a given title.
458 sub get_formats {
459     my ($self, $title_id) = @_;
460     $self->do_client_auth() if (!$self->{bearer_token});
461     $self->get_library_info() if (!$self->{collection_token});
462     my $collection_token = $self->{collection_token};
463
464     my $formats = [];
465
466     my $format_req = {
467         method  => 'GET',
468         uri     => $self->{discovery_base_uri} . "/collections/$collection_token/products/$title_id/metadata"
469     };
470     if (my $format_res = $self->handle_http_request($format_req, $self->{session_id})) {
471         if ($format_res->{content}->{formats}) {
472             foreach my $f (@{$format_res->{content}->{formats}}) {
473                 push @$formats, { id => $f->{id}, name => $f->{name} };
474             }
475         } else {
476             $logger->info("EbookAPI: OverDrive holdings format request for title $title_id contained no format information");
477         }
478     } else {
479         $logger->error("EbookAPI: failed to retrieve OverDrive holdings formats for title $title_id");
480     }
481
482     return $formats;
483 }
484
485 # POST https://patron.api.overdrive.com/v1/patrons/me/checkouts
486 # Authorization: Bearer {OAuth patron access token}
487 # Content-Type: application/json; charset=utf-8
488
489 # Request content looks like this:
490 # {
491 #     "fields": [
492 #         {
493 #             "name": "reserveId",
494 #             "value": "76C1B7D0-17F4-4C05-8397-C66C17411584"
495 #         }
496 #     ]
497 # }
498 #
499 # Response looks like this:
500 # {
501 #     "reserveId": "76C1B7D0-17F4-4C05-8397-C66C17411584",
502 #     "expires": "10/14/2013 10:56:00 AM",
503 #     "isFormatLockedIn": false,
504 #     "formats": [
505 #         {
506 #             "reserveId": "76C1B7D0-17F4-4C05-8397-C66C17411584",
507 #             "formatType": "ebook-overdrive",
508 #             "linkTemplates": {
509 #                 "downloadLink": {
510 #                     "href": "https://patron.api.overdrive.com/v1/patrons/me/checkouts/76C1B7D0-17F4-4C05-8397-C66C17411584/formats/ebook-overdrive/downloadlink?errorpageurl={errorpageurl}&odreadauthurl={odreadauthurl}",
511 #                     ...
512 #                 },
513 #                 ...
514 #             },
515 #             ...
516 #         }
517 #     ],
518 #     ...
519 # }
520 #
521 # Our return value looks like this:
522 # {
523 #     due_date => "10/14/2013 10:56:00 AM",
524 #     formats => [
525 #         "ebook-overdrive" => "https://patron.api.overdrive.com/v1/patrons/me/checkouts/76C1B7D0-17F4-4C05-8397-C66C17411584/formats/ebook-overdrive/downloadlink?errorpageurl={errorpageurl}&odreadauthurl={odreadauthurl}",
526 #         ...
527 #     ]
528 # }
529 sub checkout {
530     my ($self, $title_id, $patron_token, $format) = @_;
531     my $request_content = {
532         fields => [
533             {
534                 name  => 'reserveId',
535                 value => $title_id
536             }
537         ]
538     };
539     if ($format) {
540         push @{$request_content->{fields}}, { name => 'formatType', value => $format };
541     }
542     my $req = {
543         method  => 'POST',
544         uri     => $self->{circulation_base_uri} . "/patrons/me/checkouts",
545         content => OpenSRF::Utils::JSON->perl2JSON($request_content)
546     };
547     if (my $res = $self->handle_http_request($req, $self->{session_id})) {
548         if ($res->{content}->{expires}) {
549             my $checkout = { due_date => $res->{content}->{expires} };
550             if (defined $res->{content}->{formats}) {
551                 my $formats = {};
552                 foreach my $f (@{$res->{content}->{formats}}) {
553                     my $ftype = $f->{formatType};
554                     $formats->{$ftype} = $f->{linkTemplates}->{downloadLink}->{href};
555                 }
556                 $checkout->{formats} = $formats;
557             }
558             return $checkout;
559         }
560         $logger->error("EbookAPI: checkout failed for OverDrive title $title_id");
561         return { error_msg => ( (defined $res->{content}) ? $res->{content} : 'Unknown checkout error' ) };
562     }
563     $logger->error("EbookAPI: no response received from OverDrive server");
564     return;
565 }
566
567 # renew is not supported by OverDrive API
568 sub renew {
569     $logger->error("EbookAPI: OverDrive API does not support renewals");
570     return { error_msg => "Title cannot be renewed." };
571 }
572
573 # NB: A title cannot be checked in once a format has been locked in.
574 # Successful checkin returns an HTTP 204 response with no content.
575 # DELETE https://patron.api.overdrive.com/v1/patrons/me/checkouts/08F7D7E6-423F-45A6-9A1E-5AE9122C82E7
576 # Authorization: Bearer {OAuth patron access token}
577 # Host: patron.api.overdrive.com
578 sub checkin {
579     my ($self, $title_id, $patron_token) = @_;
580     my $req = {
581         method  => 'DELETE',
582         uri     => $self->{circulation_base_uri} . "/patrons/me/checkouts/$title_id"
583     };
584     if (my $res = $self->handle_http_request($req, $self->{session_id})) {
585         if ($res->{status} =~ /^204/) {
586             return {};
587         } else {
588             $logger->error("EbookAPI: checkin failed for OverDrive title $title_id");
589             return { error_msg => ( (defined $res->{content}) ? $res->{content} : 'Checkin failed' ) };
590         }
591     }
592     $logger->error("EbookAPI: no response received from OverDrive server");
593     return;
594 }
595
596 sub place_hold {
597     my ($self, $title_id, $patron_token, $email) = @_;
598     my $fields = [
599         {
600             name  => 'reserveId',
601             value => $title_id
602         }
603     ];
604     if ($email) {
605         push @$fields, { name => 'emailAddress', value => $email };
606         # TODO: Use autoCheckout=true when we have a patron email?
607     } else {
608         push @$fields, { name => 'ignoreEmail', value => 'true' };
609     }
610     my $request_content = { fields => $fields };
611     my $req = {
612         method  => 'POST',
613         uri     => $self->{circulation_base_uri} . "/patrons/me/holds",
614         content => OpenSRF::Utils::JSON->perl2JSON($request_content)
615     };
616     if (my $res = $self->handle_http_request($req, $self->{session_id})) {
617         if ($res->{content}->{holdPlacedDate}) {
618             return {
619                 queue_position => $res->{content}->{holdListPosition},
620                 queue_size => $res->{content}->{numberOfHolds},
621                 expire_date => (defined $res->{content}->{holdExpires}) ? $res->{content}->{holdExpires} : undef
622             };
623         }
624         $logger->error("EbookAPI: place hold failed for OverDrive title $title_id");
625         return { error_msg => "Could not place hold." };
626     }
627     $logger->error("EbookAPI: no response received from OverDrive server");
628     return;
629 }
630
631 sub cancel_hold {
632     my ($self, $title_id, $patron_token) = @_;
633     my $req = {
634         method  => 'DELETE',
635         uri     => $self->{circulation_base_uri} . "/patrons/me/holds/$title_id"
636     };
637     if (my $res = $self->handle_http_request($req, $self->{session_id})) {
638         if ($res->{status} =~ /^204/) {
639             return {};
640         } else {
641             $logger->error("EbookAPI: cancel hold failed for OverDrive title $title_id");
642             return { error_msg => ( (defined $res->{content}) ? $res->{content} : 'Could not cancel hold' ) };
643         }
644     }
645     $logger->error("EbookAPI: no response received from OverDrive server");
646     return;
647 }
648
649 # List of patron checkouts:
650 # GET http://patron.api.overdrive.com/v1/patrons/me/checkouts
651 # User-Agent: {Your application}
652 # Authorization: Bearer {OAuth patron access token}
653 # Host: patron.api.overdrive.com
654 #
655 # Response looks like this:
656 # {
657 #     "totalItems": 4,
658 #     "totalCheckouts": 2,
659 #     "checkouts": [
660 #         {
661 #             "reserveId": "A03EAC2C-C088-46C6-B9E9-59D6C11A3596",
662 #             "expires": "2015-08-11T18:53:00Z",
663 #             ...
664 #         }
665 #     ],
666 #     ...
667 # }
668 #
669 # To get title metadata (e.g. title/author), do get_title_info(reserveId).
670 sub get_patron_checkouts {
671     my $self = shift;
672     my $patron_token = shift;
673     if (my $res = $self->do_get_patron_xacts('checkouts', $patron_token)) {
674         my $checkouts = [];
675         foreach my $checkout (@{$res->{content}->{checkouts}}) {
676             my $title_id = $checkout->{reserveId};
677             my $title_info = $self->get_title_info($title_id);
678             my $formats = {};
679             foreach my $f (@{$checkout->{formats}}) {
680                 my $ftype = $f->{formatType};
681                 $formats->{$ftype} = $f->{linkTemplates}->{downloadLink}->{href};
682             };
683             push @$checkouts, {
684                 title_id => $title_id,
685                 due_date => $checkout->{expires},
686                 title => $title_info->{title},
687                 author => $title_info->{author},
688                 formats => $formats
689             }
690         };
691         $self->{checkouts} = $checkouts;
692         return $self->{checkouts};
693     } else {
694         $logger->error("EbookAPI: unable to retrieve OverDrive checkouts for patron " . $self->{patron_barcode});
695         return;
696     }
697 }
698
699 sub get_patron_holds {
700     my $self = shift;
701     my $patron_token = shift;
702     if (my $res = $self->do_get_patron_xacts('holds', $patron_token)) {
703         my $holds = [];
704         foreach my $hold (@{$res->{content}->{holds}}) {
705             my $title_id = $hold->{reserveId};
706             my $title_info = $self->get_title_info($title_id);
707             my $this_hold = {
708                 title_id => $title_id,
709                 queue_position => $hold->{holdListPosition},
710                 queue_size => $hold->{numberOfHolds},
711                 # TODO: special handling for ready-to-checkout holds
712                 is_ready => ( $hold->{actions}->{checkout} ) ? 1 : 0,
713                 is_frozen => ( $hold->{holdSuspension} ) ? 1 : 0,
714                 create_date => $hold->{holdPlacedDate},
715                 expire_date => ( $hold->{holdExpires} ) ? $hold->{holdExpires} : '-',
716                 title => $title_info->{title},
717                 author => $title_info->{author}
718             };
719             # TODO: hold suspensions
720             push @$holds, $this_hold;
721         }
722         $self->{holds} = $holds;
723         return $self->{holds};
724     } else {
725         $logger->error("EbookAPI: unable to retrieve OverDrive holds for patron " . $self->{patron_barcode});
726         return;
727     }
728 }
729
730 # generic function for retrieving patron transactions
731 sub do_get_patron_xacts {
732     my $self = shift;
733     my $xact_type = shift;
734     my $patron_token = shift;
735     if (!$patron_token) {
736         if ($self->{patron_barcode}) {
737             $self->do_client_auth() if (!$self->{bearer_token});
738             $self->do_patron_auth();
739         } else {
740             $logger->error("EbookAPI: Cannot retrieve OverDrive $xact_type with no patron information");
741         }
742     }
743     my $req = {
744         method  => 'GET',
745         uri     => $self->{circulation_base_uri} . "/patrons/me/$xact_type"
746     };
747     return $self->handle_http_request($req, $self->{session_id});
748 }
749
750 # get download URL for checked-out title
751 sub do_get_download_link {
752     my ($self, $request_link) = @_;
753     # Request links use the same domain as the circulation base URI, but they
754     # are apparently always plain HTTP.  The request link still works if you
755     # use HTTPS instead.  So, if our circulation base URI uses HTTPS, let's
756     # force the request link to HTTPS too, for two reasons:
757     # 1. A preference for HTTPS is implied by the library's circulation base
758     #    URI setting.
759     # 2. The base URI of the request link has to match the circulation base URI
760     #    (including the same protocol) in order for the handle_http_request()
761     #    method above to automatically re-authenticate the patron, if required.
762     if ($self->{circulation_base_uri} =~ /^https:/) {
763         $request_link =~ s/^http:/https:/;
764     }
765     my $req = {
766         method  => 'GET',
767         uri     => $request_link
768     };
769     if (my $res = $self->handle_http_request($req, $self->{session_id})) {
770         if ($res->{content}->{links}->{contentlink}->{href}) {
771             return { url => $res->{content}->{links}->{contentlink}->{href} };
772         }
773         return { error_msg => ( (defined $res->{content}) ? $res->{content} : 'Could not get content link' ) };
774     }
775     $logger->error("EbookAPI: no response received from OverDrive server");
776     return;
777 }
778
779 1;