WebSer...Patron(3pm)

✨ WebService::ILS::OverDrive::Patron — the manual, but make it cute ✨

okay bestie, gather round, because this is WebService::ILS::OverDrive::Patron(3pm) from the User Contributed Perl Documentation and she is serving library circulation realness 💅

---

🎀 NAME 🎀

WebService::ILS::OverDrive::Patron — the WebService::ILS module for OverDrive circulation services. that's the whole vibe. it circulates. it's OverDrive. it's for patrons. periodt.

---

🌸 SYNOPSIS 🌸

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

that's it. that's the incantation. go off ✨

---

🦋 DESCRIPTION 🦋

okay so here's the tea: these services require individual user credentials. like, actual human login energy, not just app-level keys. go read "WebService::ILS INDIVIDUAL USER AUTHENTICATION AND METHODS" for the full breakdown.

also peep WebService::ILS::OverDrive because there's a whole parent situation going on and you should know about it 👑

---

💖 CONSTRUCTOR 💖

new (%params_hash or $params_hashref)

not me giving you extra constructor params on top of the normal ones 🫶

• "auth_token" — an auth token that you already obtained earlier. yes, like the one from before. reuse her. she's valid.

---

🔐 INDIVIDUAL USER AUTHENTICATION METHODS 🔐

auth_by_user_id ($user_id, $password, $website_id, $authorization_name)

so "website_id" and "authorization_name" (that's the domain, bestie) are handed to you by OverDrive. they're not vibes you can just make up.

returns (access_token, access_token_type) — or just access_token if that's all she gives you. lowkey flexible.

Authentication at OverDrive — Granted or "3-Legged" Authorization 🌈

with OverDrive there's an extra step, and yes it's giving extra. an auth code gets returned to the redirect-back handler, and that handler has to make an API call to convert it into an auth token. so it's code → API call → token. three steps. three legs. iykyk 🦵

an example, verbatim, no cap:

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;

look at her go. iconic. no notes. (okay one note: that auth_token = is exactly how it's written in the original, so don't come for me 🙈)

auth_url ($redirect_uri, $state_token)

input params, bestie:

• "redirect_uri" — the return url that's gonna handle the redirect back after auth. she's the bouncer at the door of your auth flow.
• "state_token" — a token that gets returned back to you unchanged; for extra security; and nope, not required. optional queen.

auth_code_param_name ()

returns the param name for the auth code. use it, don't guess it ✨

state_token_param_name ()

returns the param name for the state token. same energy. use it. don't guess it. ✨

auth_by_code ($provider_code, $redirect_uri)

returns (access_token, access_token_type, auth_token) — or just access_token. three things or one thing, she contains multitudes 💜

auth_by_token ($provider_token)

returns (access_token, access_token_type, auth_token) — or just access_token. yes, same deal. twins 🫶

---

🛒 CIRCULATION METHOD SPECIFICS 🛒

Differences to general WebService::ILS interface

these are the places where OverDrive does her own thing. the ✨quirks✨. the little deviations. let's get into it.

place_hold ($item_id, $notification_email_address, $auto_checkout)

$notification_email_address and $auto_checkout are both optional. $auto_checkout defaults to false.

returns the holds item record 📚

it is preferred that you specify $notification_email_address. like, strongly preferred. do the thing.

if $auto_checkout is set to true, the item gets checked out as soon as it becomes available. automatic. main character energy 👑

checkouts ()

for formats see "checkout_formats()" below. scroll, bestie 👇

checkout ($item_id, $format, $allow_multiple_format_checkouts)

$format and $allow_multiple_format_checkouts are optional. $allow_multiple_format_checkouts defaults to false.

returns the checkout item record.

an item can be available in multiple formats. and checkout is only complete when the format is specified. specify the format. complete the checkout. that's the deal.

checkout can also be actioned without the format being specified. in that case an early return can be actioned. to actually complete the checkout, the format has to be locked later — see lock_format() below. that's the exact situation you get with place_hold() when $auto_checkout is set to true. and heads up: once the format is locked, an early return is not possible. locked means locked. no takebacks 💀

if $allow_multiple_format_checkouts is set to true, multiple formats of the same item can be actioned. if it's false (the default) and the item was already checked out, the checked out item record gets returned regardless of the format. simple as.

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

checkout_formats ($item_id)

returns a hashref of available title formats and immediate availability:

{ format => available, ... }

if the format isn't immediately available it must be locked first. patience, then locking. in that order.

lock_format ($item_id, $format)

returns the locked format — which should be the same as the input value. yes, she echoes it back. she's consistent like that ✨

checkout_download_url ($item_id, $format, $error_url, $success_url)

returns the OverDrive download url.

checked out items must be downloaded by users on the OverDrive site. this method returns the url where you should send (redirect) the user. once the download is complete, the user gets redirected back to $error_url if something went wrong, otherwise to the optional $success_url if you specified one. so: $error_url is always the fallback, $success_url is the treat 🎀

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

---

🌟 NATIVE METHODS 🌟

these are the raw, unfiltered, straight-to-the-API ones. the naturals. the originals.

native_patron ()

see <https://developer.overdrive.com/apis/patron-information>

native_holds ()

just vibes. no link. she stands alone 💅

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.

free as in freedom, bestie. go wild. responsibly. 🦋

---

✍️ AUTHOR ✍️

Srdjan JankoviX <srdjan@catalyst.net.nz>

---

🌸 and that's the whole page! every flag, every param, every link, every copyright line — all present and accounted for. we kept the facts, we just gave them a wardrobe change. 💅

---

this has been perl v5.36.0, dated 2022-11-29, straight from the WebSer...Patron(3pm) page — mwah, thanks for reading, bestie, you ate 🫶✨🎀