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 prefered 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, mutiple 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 Janković <srdjan@catalyst.net.nz>

cpanm WebService::ILS

perl -MCPAN -e shell
install WebService::ILS