3 # Copyright (C) 2015 BC Libraries Cooperative
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.
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.
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.
19 package OpenILS::Application::EbookAPI::OverDrive;
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;
37 my( $class, $args ) = @_;
38 $class = ref $class || $class;
39 return bless $args, $class;
49 return $self->{vendor};
54 return $self->{session_id};
59 return $self->{account_id};
64 return $self->{websiteid};
67 sub authorizationname {
69 return $self->{authorizationname};
74 return $self->{basic_token};
79 return $self->{bearer_token};
82 sub collection_token {
84 return $self->{collection_token};
87 sub granted_auth_uri {
89 return $self->{granted_auth_uri};
92 sub password_required {
94 return $self->{password_required};
99 return $self->{patron_token};
104 my $ou = $self->{ou};
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';
111 my $account_id = OpenILS::Application::AppUtils->ou_ancestor_setting_value($ou, 'ebook_api.overdrive.account_id');
113 $self->{account_id} = $account_id;
115 $logger->error("EbookAPI: no OverDrive account ID found for org unit $ou");
119 my $websiteid = OpenILS::Application::AppUtils->ou_ancestor_setting_value($ou, 'ebook_api.overdrive.websiteid');
121 $self->{websiteid} = $websiteid;
123 $logger->error("EbookAPI: no OverDrive website ID found for org unit $ou");
127 my $authorizationname = OpenILS::Application::AppUtils->ou_ancestor_setting_value($ou, 'ebook_api.overdrive.authorizationname');
128 if ($authorizationname) {
129 $self->{authorizationname} = $authorizationname;
131 $logger->error("EbookAPI: no OverDrive authorization name found for org unit $ou");
135 my $basic_token = OpenILS::Application::AppUtils->ou_ancestor_setting_value($ou, 'ebook_api.overdrive.basic_token');
137 $self->{basic_token} = $basic_token;
139 $logger->error("EbookAPI: no OverDrive basic token found for org unit $ou");
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;
148 my $password_required = OpenILS::Application::AppUtils->ou_ancestor_setting_value($ou, 'ebook_api.overdrive.password_required') || 0;
149 $self->{password_required} = $password_required;
155 # Wrapper method for HTTP requests.
156 sub handle_http_request {
160 # Prep our request using defaults.
161 $req->{method} = 'GET' if (!$req->{method});
162 $req = $self->set_http_headers($req);
165 my $res = $self->request($req, $self->{session_id});
167 $logger->info("EbookAPI: raw OverDrive HTTP response: " . Dumper $res);
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...");
173 # Always re-auth client to ensure we have an up-to-date client token.
174 $self->do_client_auth();
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();
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});
188 # For any non-401 response (including no response at all),
189 # just return whatever response we got (if any).
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 {
201 $req->{headers} = {} if (!$req->{headers});
202 if (!$req->{headers}->{Authorization}) {
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};
214 $auth_type = 'Basic';
215 $token = $self->{basic_token};
218 $logger->error("EbookAPI: unable to set HTTP Authorization header without token");
219 $logger->error("EbookAPI: failed request: " . Dumper $req);
222 $req->{headers}->{Authorization} = "$auth_type $token";
228 # POST /token HTTP/1.1
229 # Host: oauth.overdrive.com
230 # Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW
232 # grant_type=client_credentials
237 uri => 'https://oauth.overdrive.com/token',
239 'Authorization' => 'Basic ' . $self->{basic_token},
240 'Content-Type' => 'application/x-www-form-urlencoded;charset=UTF-8'
242 content => 'grant_type=client_credentials'
244 my $res = $self->request($req, $self->{session_id});
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();
254 $logger->error("EbookAPI: bearer token not received from OverDrive API");
255 $logger->error("EbookAPI: bad response: " . Dumper $res);
258 $logger->error("EbookAPI: no client authentication response from OverDrive API");
266 if ($self->{granted_auth_uri}) {
267 return $self->do_granted_patron_auth(@args);
269 return $self->do_basic_patron_auth(@args);
274 sub do_granted_patron_auth {
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
282 # grant_type=password&username=1234567890&password=1234&scope=websiteid:12345 authorizationname:default
284 # grant_type=password&username=1234567890&password=[ignore]&password_required=false&scope=websiteid:12345 authorizationname:default
285 sub do_basic_patron_auth {
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");
297 if (!$self->{patron_barcode}) {
298 $logger->error("EbookAPI: Cannot authenticate patron with unknown barcode");
300 $barcode = $self->{patron_barcode};
304 # TODO handle cached/expired tokens?
305 # Making a request using an expired token will give a 401 Unauthorized error.
306 # Handle this appropriately.
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";
315 $content .= '&password=xxx&password_required=false'
317 $content .= '&scope=websiteid:' . $self->{websiteid} . ' authorizationname:' . $self->{authorizationname};
321 uri => 'https://oauth-patron.overdrive.com/patrontoken',
323 'Authorization' => 'Basic ' . $self->{basic_token},
324 'Content-Type' => 'application/x-www-form-urlencoded;charset=UTF-8'
328 my $res = $self->request($req, $self->{session_id});
330 if (defined ($res)) {
331 if ($res->{content}->{access_token}) {
332 $self->{patron_token} = $res->{content}->{access_token};
333 return $self->{patron_token};
335 $logger->error("EbookAPI: patron access token not received from OverDrive API");
338 $logger->error("EbookAPI: no patron authentication response from OverDrive API");
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 {
349 my $library_id = $self->{account_id};
352 uri => $self->{discovery_base_uri} . "/libraries/$library_id"
354 if (my $res = $self->handle_http_request($req, $self->{session_id})) {
355 $self->{collection_token} = $res->{content}->{collectionToken};
356 return $self->{collection_token};
358 $logger->error("EbookAPI: OverDrive Library Account API request failed");
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
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};
375 uri => $self->{discovery_base_uri} . "/collections/$collection_token/products/$title_id/metadata"
377 if (my $res = $self->handle_http_request($req, $self->{session_id})) {
378 if ($res->{content}->{title}) {
380 title => $res->{content}->{title},
381 author => $res->{content}->{creators}[0]{name}
383 # Append format information (useful for checkouts).
384 $info->{formats} = $self->get_formats($title_id);
387 $logger->error("EbookAPI: OverDrive metadata lookup failed for $title_id");
390 $logger->error("EbookAPI: no metadata response from OverDrive API");
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 {
401 my $title_id = shift;
402 $self->do_client_auth() if (!$self->{bearer_token});
403 $self->get_library_info() if (!$self->{collection_token});
406 uri => $self->{discovery_base_uri} . "/collections/" . $self->{collection_token} . "/products/$title_id/availability"
408 if (my $res = $self->handle_http_request($req, $self->{session_id})) {
409 return $res->{content}->{available};
411 $logger->error("EbookAPI: could not retrieve OverDrive availability for title $title_id");
416 # Holdings lookup has two parts:
418 # 1. Copy availability: as above, but grab more details.
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
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};
432 # prepare data structure to be used as return value
435 copies_available => 0,
439 # request copy availability totals
442 uri => $self->{discovery_base_uri} . "/collections/$collection_token/products/$title_id/availability"
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};
448 $logger->error("EbookAPI: failed to retrieve OverDrive holdings counts for title $title_id");
451 # request available formats
452 $holdings->{formats} = $self->get_formats($title_id);
457 # Returns a list of available formats for a given title.
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};
468 uri => $self->{discovery_base_uri} . "/collections/$collection_token/products/$title_id/metadata"
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} };
476 $logger->info("EbookAPI: OverDrive holdings format request for title $title_id contained no format information");
479 $logger->error("EbookAPI: failed to retrieve OverDrive holdings formats for title $title_id");
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
489 # Request content looks like this:
493 # "name": "reserveId",
494 # "value": "76C1B7D0-17F4-4C05-8397-C66C17411584"
499 # Response looks like this:
501 # "reserveId": "76C1B7D0-17F4-4C05-8397-C66C17411584",
502 # "expires": "10/14/2013 10:56:00 AM",
503 # "isFormatLockedIn": false,
506 # "reserveId": "76C1B7D0-17F4-4C05-8397-C66C17411584",
507 # "formatType": "ebook-overdrive",
510 # "href": "https://patron.api.overdrive.com/v1/patrons/me/checkouts/76C1B7D0-17F4-4C05-8397-C66C17411584/formats/ebook-overdrive/downloadlink?errorpageurl={errorpageurl}&odreadauthurl={odreadauthurl}",
521 # Our return value looks like this:
523 # due_date => "10/14/2013 10:56:00 AM",
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}",
530 my ($self, $title_id, $patron_token, $format) = @_;
531 my $request_content = {
540 push @{$request_content->{fields}}, { name => 'formatType', value => $format };
544 uri => $self->{circulation_base_uri} . "/patrons/me/checkouts",
545 content => OpenSRF::Utils::JSON->perl2JSON($request_content)
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}) {
552 foreach my $f (@{$res->{content}->{formats}}) {
553 my $ftype = $f->{formatType};
554 $formats->{$ftype} = $f->{linkTemplates}->{downloadLink}->{href};
556 $checkout->{formats} = $formats;
560 $logger->error("EbookAPI: checkout failed for OverDrive title $title_id");
561 return { error_msg => ( (defined $res->{content}) ? $res->{content} : 'Unknown checkout error' ) };
563 $logger->error("EbookAPI: no response received from OverDrive server");
567 # renew is not supported by OverDrive API
569 $logger->error("EbookAPI: OverDrive API does not support renewals");
570 return { error_msg => "Title cannot be renewed." };
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
579 my ($self, $title_id, $patron_token) = @_;
582 uri => $self->{circulation_base_uri} . "/patrons/me/checkouts/$title_id"
584 if (my $res = $self->handle_http_request($req, $self->{session_id})) {
585 if ($res->{status} =~ /^204/) {
588 $logger->error("EbookAPI: checkin failed for OverDrive title $title_id");
589 return { error_msg => ( (defined $res->{content}) ? $res->{content} : 'Checkin failed' ) };
592 $logger->error("EbookAPI: no response received from OverDrive server");
597 my ($self, $title_id, $patron_token, $email) = @_;
605 push @$fields, { name => 'emailAddress', value => $email };
606 # TODO: Use autoCheckout=true when we have a patron email?
608 push @$fields, { name => 'ignoreEmail', value => 'true' };
610 my $request_content = { fields => $fields };
613 uri => $self->{circulation_base_uri} . "/patrons/me/holds",
614 content => OpenSRF::Utils::JSON->perl2JSON($request_content)
616 if (my $res = $self->handle_http_request($req, $self->{session_id})) {
617 if ($res->{content}->{holdPlacedDate}) {
619 queue_position => $res->{content}->{holdListPosition},
620 queue_size => $res->{content}->{numberOfHolds},
621 expire_date => (defined $res->{content}->{holdExpires}) ? $res->{content}->{holdExpires} : undef
624 $logger->error("EbookAPI: place hold failed for OverDrive title $title_id");
625 return { error_msg => "Could not place hold." };
627 $logger->error("EbookAPI: no response received from OverDrive server");
632 my ($self, $title_id, $patron_token) = @_;
635 uri => $self->{circulation_base_uri} . "/patrons/me/holds/$title_id"
637 if (my $res = $self->handle_http_request($req, $self->{session_id})) {
638 if ($res->{status} =~ /^204/) {
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' ) };
645 $logger->error("EbookAPI: no response received from OverDrive server");
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
655 # Response looks like this:
658 # "totalCheckouts": 2,
661 # "reserveId": "A03EAC2C-C088-46C6-B9E9-59D6C11A3596",
662 # "expires": "2015-08-11T18:53:00Z",
669 # To get title metadata (e.g. title/author), do get_title_info(reserveId).
670 sub get_patron_checkouts {
672 my $patron_token = shift;
673 if (my $res = $self->do_get_patron_xacts('checkouts', $patron_token)) {
675 foreach my $checkout (@{$res->{content}->{checkouts}}) {
676 my $title_id = $checkout->{reserveId};
677 my $title_info = $self->get_title_info($title_id);
679 foreach my $f (@{$checkout->{formats}}) {
680 my $ftype = $f->{formatType};
681 $formats->{$ftype} = $f->{linkTemplates}->{downloadLink}->{href};
684 title_id => $title_id,
685 due_date => $checkout->{expires},
686 title => $title_info->{title},
687 author => $title_info->{author},
691 $self->{checkouts} = $checkouts;
692 return $self->{checkouts};
694 $logger->error("EbookAPI: unable to retrieve OverDrive checkouts for patron " . $self->{patron_barcode});
699 sub get_patron_holds {
701 my $patron_token = shift;
702 if (my $res = $self->do_get_patron_xacts('holds', $patron_token)) {
704 foreach my $hold (@{$res->{content}->{holds}}) {
705 my $title_id = $hold->{reserveId};
706 my $title_info = $self->get_title_info($title_id);
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 create_date => $hold->{holdPlacedDate},
714 expire_date => ( $hold->{holdExpires} ) ? $hold->{holdExpires} : '-',
715 title => $title_info->{title},
716 author => $title_info->{author}
718 # TODO: hold suspensions
719 push @$holds, $this_hold;
721 $self->{holds} = $holds;
722 return $self->{holds};
724 $logger->error("EbookAPI: unable to retrieve OverDrive holds for patron " . $self->{patron_barcode});
729 # generic function for retrieving patron transactions
730 sub do_get_patron_xacts {
732 my $xact_type = shift;
733 my $patron_token = shift;
734 if (!$patron_token) {
735 if ($self->{patron_barcode}) {
736 $self->do_client_auth() if (!$self->{bearer_token});
737 $self->do_patron_auth();
739 $logger->error("EbookAPI: Cannot retrieve OverDrive $xact_type with no patron information");
744 uri => $self->{circulation_base_uri} . "/patrons/me/$xact_type"
746 return $self->handle_http_request($req, $self->{session_id});
749 # get download URL for checked-out title
750 sub do_get_download_link {
751 my ($self, $request_link) = @_;
752 # Request links use the same domain as the circulation base URI, but they
753 # are apparently always plain HTTP. The request link still works if you
754 # use HTTPS instead. So, if our circulation base URI uses HTTPS, let's
755 # force the request link to HTTPS too, for two reasons:
756 # 1. A preference for HTTPS is implied by the library's circulation base
758 # 2. The base URI of the request link has to match the circulation base URI
759 # (including the same protocol) in order for the handle_http_request()
760 # method above to automatically re-authenticate the patron, if required.
761 if ($self->{circulation_base_uri} =~ /^https:/) {
762 $request_link =~ s/^http:/https:/;
768 if (my $res = $self->handle_http_request($req, $self->{session_id})) {
769 if ($res->{content}->{links}->{contentlink}->{href}) {
770 return { url => $res->{content}->{links}->{contentlink}->{href} };
772 return { error_msg => ( (defined $res->{content}) ? $res->{content} : 'Could not get content link' ) };
774 $logger->error("EbookAPI: no response received from OverDrive server");