NAME

       WebService::ILS::OverDrive::Patron - WebService::ILS module for OverDrive circulation
       services

SYNOPSIS

           use WebService::ILS::OverDrive::Patron;

DESCRIPTION

       These services require individual user credentials.  See "WebService::ILS INDIVIDUAL USER
       AUTHENTICATION AND METHODS"

       See WebService::ILS::OverDrive

CONSTRUCTOR

   new (%params_hash or $params_hashref)
       Additional constructor params:

       "auth_token" => auth token as previously obtained

INDIVIDUAL USER AUTHENTICATION METHODS

   auth_by_user_id ($user_id, $password, $website_id, $authorization_name)
       "website_id" and "authorization_name" (domain) are provided by OverDrive

       Returns (access_token, access_token_type) or access_token

   Authentication at OverDrive - Granted or "3-Legged" Authorization
       With OverDrive there's an extra step - an auth code is returned to the redirect back
       handler that needs to make an API call to convert it into a auth token.

       An example:

           my $overdrive = WebService::ILS::OverDrive::Patron({
               client_id => $client_id,
               client_secret => $client_secret,
               library_id => $library_id,
           });
           my $redirect_url = $overdrive->auth_url("http://myapp.com/overdrive-auth");
           $response->redirect($redirect_url);
           ...
           /overdrive-auth handler:
           my $auth_code = $req->param( $overdrive->auth_code_param_name )
               or some_error_handling(), return;
           # my $state = $req->param( $overdrive->state_token_param_name )...
           local $@;
           eval { $overdrive->auth_by_code( $auth_code ) };
           if ($@) { some_error_handling(); return; }
           $session{overdrive_access_token} = $access_token;
           $session{overdrive_access_token_type} = $access_token_type;
           $session{overdrive_auth_token} = $auth_token;
           ...
           Somewhere else in your app:
           my $ils = WebService::ILS::Provider({
               client_id => $client_id,
               client_secret => $client_secret,
               access_token => $session{overdrive_access_token},
               access_token_type => $session{overdrive_access_token_type},
               auth_token = $session{overdrive_auth_token}
           });
           my $checkouts = $overdrive->checkouts;

   auth_url ($redirect_uri, $state_token)
       Input params:

       "redirect_uri" => return url which will handle redirect back after auth
       "state_token"  => a token that is returned back unchanged;
                         for additional security; not required

   auth_code_param_name ()
   state_token_param_name ()
   auth_by_code ($provider_code, $redirect_uri)
       Returns (access_token, access_token_type, auth_token) or access_token

   auth_by_token ($provider_token)
       Returns (access_token, access_token_type, auth_token) or access_token

CIRCULATION METHOD SPECIFICS

       Differences to general WebService::ILS interface

   place_hold ($item_id, $notification_email_address, $auto_checkout)
       $notification_email_address and $auto_checkout are optional.  $auto_checkout defaults to
       false.

       Returns holds item record

       It is preferred that the $notification_email_address is specified.

       If $auto_checkout is set to true, the item will be checked out as soon as it becomes
       available.

   checkouts ()
       For formats see "checkout_formats()" below

   checkout ($item_id, $format, $allow_multiple_format_checkouts)
       $format and $allow_multiple_format_checkouts are optional.
       $allow_multiple_format_checkouts defaults to false.

       Returns checkout item record

       An item can be available in multiple formats. Checkout is complete only when the format is
       specified.

       Checkout can be actioned without format being specified. In that case an early return can
       be actioned. To complete checkout format must be locked later (see lock_format() below).
       That would be the case with place_hold() with $auto_checkout set to true. Once format is
       locked, an early return is not possible.

       If $allow_multiple_format_checkouts flag is set to true, multiple formats of the same item
       can be acioned. If it is false (default) and the item was already checked out, the checked
       out item record will be returned regardless of the format.

       Checkout record will have an extra field "format" if format is locked in.

   checkout_formats ($item_id)
       Returns a hashref of available title formats and immediate availability

         { format => available, ... }

       If format is not immediately available it must be locked first

   lock_format ($item_id, $format)
       Returns locked format (should be the same as the input value)

   checkout_download_url ($item_id, $format, $error_url, $success_url)
       Returns OverDrive download url

       Checked out items must be downloaded by users on the OverDrive site.  This method returns
       the url where the user should be sent to (redirected).  Once the download is complete,
       user will be redirected back to $error_url in case of an error, otherwise to optional
       $success_url if specified.

       See <https://developer.overdrive.com/apis/download>

NATIVE METHODS

   native_patron ()
       See <https://developer.overdrive.com/apis/patron-information>

   native_holds ()
   native_place_hold ($item_id, $notification_email_address, $auto_checkout)
       See <https://developer.overdrive.com/apis/holds>

   native_checkouts ()
   native_checkout_info ($item_id)
   native_checkout ($item_id, $format, $allow_multiple_format_checkouts)
   native_checkout_formats ($item_id)
   native_lock_format ($item_id, $format)
       See <https://developer.overdrive.com/apis/checkouts>

LICENSE

       Copyright (C) Catalyst IT NZ Ltd Copyright (C) Bywater Solutions

       This library is free software; you can redistribute it and/or modify it under the same
       terms as Perl itself.

AUTHOR

       Srdjan JankoviX <srdjan@catalyst.net.nz>