NAME

       WebService::ILS - Standardised library discovery/circulation services

SYNOPSIS

           use WebService::ILS::<Provider Subclass>;
           my $ils = WebService::ILS::<Provider Subclass>->new({
               client_id => $client_id,
               client_secret => $client_secret
           });
           my %search_params = (
               query => "Some keyword",
               sort => "rating",
           );
           my $result = $ils->search(\%search_params);
           foreach (@{ $result->{items} }) {
               ...
           }
           foreach (2..$result->{pages}) {
               $search_params{page} = $_;
               my $next_results = $ils->search(\%search_params);
               ...
           }

           or

           my $native_result = $ils->native_search(\%native_search_params);

DESCRIPTION

       WebService::ILS is an attempt to create a standardised interface for online library
       services providers.

       In addition, native API interface is provided.

       Here we will describe constructor parameters and methods common to all service providers.
       Diversions and native interfaces are documented in corresponding modules.

   Supported service providers
       WebService::ILS::OverDrive::Library
           OverDrive Library API <https://developer.overdrive.com/discovery-apis>

       WebService::ILS::OverDrive::Patron
           OverDrive Circulation API <https://developer.overdrive.com/circulation-apis>

INTERFACE

   Error handling
       Method calls will die on error. $@ will contain a multi-line string.  See
       "error_message()" below.

   Item record
       Item record is returned by many methods, so we specify it here.

       "id"
       "isbn"
       "title"
       "subtitle"
       "description"
       "author"
       "publisher"
       "publication_date"
       "language"
       "rating"         => user ratings metrics
       "popularity"     => checkout metrics
       "subjects"       => subject categories (tags)
       "facets"         => a hashref of facet => [values]
       "media"          => book, e-book, video, audio etc
       "formats"        => an arrayref of available formats
       "images"         => a hashref of size => url
       "encryption_key" => for decryption purposes
       "drm"            => subject to drm

       Not all fields are available for all service providers.  Field values are not
       standardised.

CONSTRUCTOR

   new (%params_hash or $params_hashref)
       Client (vendor) related constructor params, given by service provider:

       "client_id"     => client (vendor) identifier
       "client_secret" => secret key (password)
       "library_id"    => sometimes service providers provide access to different "libraries"

       General constructor params:

       "user_agent"        => LWP::UserAgent or a derivative; usually not needed, one is created
       for you.
       "user_agent_params" => LWP::UserAgent constructor params so you don't need to create user
       agent yourself
       "access_token"      => as returned from the provider authentication system
       "access_token_type" => as returned from the provider authentication system

       These are also read-only attributes

       Not all of client/library params are required for all service providers.

ATTRIBUTES

   user_agent
       As provided to constructor, or auto created. Useful if one wants to change user agent
       attributes on the fly, eg

           $ils->user_agent->timeout(120);

DISCOVERY METHODS

   search ($params_hashref)
       Input params:

       "query"     => query (search) string
       "page_size" => number of items per results page
       "page"      => wanted page number
       "sort"      => resultset sort option (see below)

       Sort  options are either an array or a comma separated string of options:

       "publication_date" => date title was published
       "available_date"   => date title became available for users
       "rating"           => number of items per results page

       Sort order can be added after option with ":", eg "publication_date:desc,rating:desc"

       Returns search results record:

       "items"      => an array of item records
       "page_size"  => number of items per results page
       "page"       => results page number
       "pages"      => total number of pages
       "total"      => total number of items found by the search

   item_metadata ($item_id)
       Returns item record

   item_availability ($item_id)
       Returns item availability record:

       "id"
       "available"        => boolean
       "copies_available" => number of copies available
       "copies_owned"     => number of copies owned
       "type"             => availability type, provider dependant

       Not all fields are available for all service providers.  For example, some will provide
       "copies_available", making "available" redundant, whereas others will just provide
       "available".

   is_item_available ($item_id)
       Returns boolean

       Simplified version of item_availability()

INDIVIDUAL USER AUTHENTICATION AND METHODS

   user_id / password
       Provider authentication API is used to get an authorized session.

       auth_by_user_id($user_id, $password)

       An example:

           my $ils = WebService::ILS::Provider({
               client_id => $client_id,
               client_secret => $client_secret,
           });
           eval { $ils->auth_by_user_id( $user_id, $password ) };
           if ($@) { some_error_handling(); return; }
           $session{ils_access_token} = $ils->access_token;
           $session{ils_access_token_type} = $ils->access_token_type;
           ...
           Somewhere else in your app:
           my $ils = WebService::ILS::Provider({
               client_id => $client_id,
               client_secret => $client_secret,
               access_token => $session{ils_access_token},
               access_token_type => $session{ils_access_token_type},
           });

           my $checkouts = $ils->checkouts;

   Authentication at the provider
       User is redirected to the provider authentication url, and after authenticating at the
       provider redirected back with some kind of auth token.  Requires url to handle return
       redirect from the provider.

       It can be used as an alternative to FB and Google auth.

       This is just to give an idea, specifics heavily depend on the provider

       auth_url ($redirect_back_uri)

       Returns provider authentication url to redirect to

       auth_token_param_name ()

       Returns auth code url param name

       auth_by_token ($provider_token)

       An example:

           my $ils = WebService::ILS::Provider({
               client_id => $client_id,
               client_secret => $client_secret,
           });
           my $redirect_url = $ils->auth_url("http://myapp.com/ils-auth");
           $response->redirect($redirect_url);
           ...
           After successful authentication at the provider, provider redirects
           back to specified app url (http://myapp.com/ils-auth)

           /ils-auth handler:
           my $auth_token = $req->param( $ils->auth_token_param_name )
               or some_error_handling(), return;
           local $@;
           eval { $ils->auth_by_token( $auth_token ) };
           if ($@) { some_error_handling(); return; }
           $session{ils_access_token} = $ils->access_token;
           $session{ils_access_token_type} = $ils->access_token_type;
           ...
           Somewhere else in your app:
           passing access token to the constructor as above

CIRCULATION METHODS

   patron ()
       Returns patron record:

       "id"
       "active"            => boolean
       "copies_available"  => number of copies available
       "checkout_limit"    => number of checkouts allowed
       "hold_limit"        => number of holds allowed

   holds ()
       Returns holds record:

       "total"             => number of items on hold
       "items"             => list of individual items

       In addition to Item record fields described above, item records will have:

       "placed_datetime"   => hold timestamp, with or without timezone
       "queue_position"    => user's position in the waiting queue, if available

   place_hold ($item_id)
       Returns holds item record (as described above)

       In addition, "total" field will be incorported as well.

   remove_hold ($item_id)
       Returns true to indicate success

       Returns true in case user does not have a hold on the item.  Throws exception in case of
       any other failure.

   checkouts ()
       Returns checkout record:

       "total"             => number of items on hold
       "items"             => list of individual items

       In addition to Item record fields described above, item records will have:

       "checkout_datetime" => checkout timestamp, with or without timezone
       "expires"           => date (time) checkout expires
       "url"               => download/stream url
       "files"             => an arrayref of downloadable file details title, url, size

   checkout ($item_id)
       Returns checkout item record (as described above)

       In addition, "total" field will be incorported as well.

   return ($item_id)
       Returns true to indicate success

       Returns true in case user does not have the item checked out.  Throws exception in case of
       any other failure.

NATIVE METHODS

       All Discovery and Circulation methods (with exception of remove_hold() and return(), where
       it does not make sense) have native_*() counterparts, eg native_search(),
       native_item_availability(), native_checkout() etc.

       In case of single item methods, native_item_availability(), native_checkout() etc, they
       take item_id as parameter. Otherwise, it's a hashref of HTTP request params (GET or POST).

       Return value is a record as returned by API.

       Individual provider subclasses provide additional provider specific native methods.

UTILITY METHODS

   Error constants
       "ERROR_ACCESS_TOKEN"
       "ERROR_NOT_AUTHENTICATED"

   error_message ($exception_string)
       Returns error message probably suitable for displaying to the user

       Example:

           my $res = eval { $ils->checkout($id) };
           if ($@) {
               my $msg = $ils->error_message($@);
               display($msg);
               log_error($@);
           }

   is_access_token_error ($exception_string)
       Returns true if the error is access token related

   is_not_authenticated_error ($exception_string)
       Returns true if the error is "Not authenticated"

TODO

       Federated search

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>