bookclerk_plugin_source_libro::catalog
Libro.fm catalog search, detail, related titles and purchase links.
Every call goes to the Android app's signed-out catalog API
(/api/vN/explore/…, the same prefix as LIBRARY_PATH). Requests carry
an honest Bookclerk user agent and the app's X-LibroFm-AppVer header,
which is part of the app's API contract (the signed-in client sends the
same value) and without which explore/audiobook_details answers 404.
No Authorization, device or OS headers are sent. Libro.fm's load
balancer refuses automated requests to its website pages, so this module
never fetches storefront HTML and never presents itself as a browser.
Search rows are lean (ISBN, title, authors, narrators, cover);
explore/audiobook_details adds description, genres, runtime, publisher,
series, abridged, language, list price and related titles.
This crate intentionally does not depend on bookclerk-enrich.
| Item | Kind | Summary |
|---|---|---|
LibroDetails |
struct | One title from explore/audiobook_details. |
explore_search_path |
function | Path of the app's catalog search (GET …/explore/search?q=&page=). |
search_catalog |
function | Catalog search → CatalogHits keyed by ISBN. |
catalog_detail |
function | Catalog record for one ISBN (or ISBN-leading slug). |
expand_candidates |
function | Related candidates for Discover. |
purchase_hint |
function | Resolve a Libro.fm product link for a title, by ISBN first and then by title and author. |
purchase_answer |
function | Resolve a Libro.fm product link for a title, with every for-sale listing a title search found. |
parse_details |
function | Parses one explore/audiobook_details body. |
parse_search_page |
function | Parses one catalog search response body into at most limit hits. |
CATALOG_USER_AGENT |
constant | User agent for signed-out catalog calls: names Bookclerk and its site so Libro.fm can identify (and contact) the client. |
pub struct LibroDetails {
pub audiobook: Option<CatalogHit>,
pub related: Vec<CatalogHit>,
pub for_sale: bool,
}
One title from explore/audiobook_details.
Fields
audiobook: The title itself, with its list price;Nonewhen the payload had no usable audiobook object.related: Related titles the app shows under it (lean rows, like search).for_sale: Whether Libro.fm sells the title (purchase_info.for_sale);truewhen the payload does not say.
Implements: Debug, Default
pub fn explore_search_path() -> String
Path of the app's catalog search (GET …/explore/search?q=&page=).
pub async fn search_catalog(
base_url: &str,
opts: &CatalogSearchOpts,
) -> Result<Vec<CatalogHit>>
Catalog search → CatalogHits keyed by ISBN.
base_url- Libro.fm API origin (the plugin'sbase_urlsetting).opts- Query, page and hit limit.
Returns an error when Libro.fm answers with a non-success status or a body that is not the search envelope.
pub async fn catalog_detail(
base_url: &str,
product_id: &str,
) -> Result<Option<CatalogHit>>
Catalog record for one ISBN (or ISBN-leading slug).
Prefers the app's explore/audiobook_details (description, genres,
runtime, publisher, series, abridged, language, list price). When that
misses or fails, falls back to the catalog search row whose ISBN matches
exactly, so a fuzzy hit never stands in for the requested book.
base_url- Libro.fm API origin (the plugin'sbase_urlsetting).product_id- ISBN-10/13 or{isbn}-{slug}; anything else returnsNone.
Returns an error when the details call misses and the fallback search fails.
pub async fn expand_candidates(
base_url: &str,
seed: &ExpandSeed,
limit: usize,
) -> Result<Vec<CatalogHit>>
Related candidates for Discover.
A Libro.fm seed with an ISBN gets the app's related titles from
explore/audiobook_details. Otherwise, or when that returns none, a
Libro.fm seed gets more titles by its first author and a seed from
another store gets a title-and-author search. The seed itself is never
returned. Every row is then read in full from its details
(read_in_full), since the lists leave out the language and price.
base_url- Libro.fm API origin.seed- Title the candidates relate to.limit- Most candidates to return.
Returns an error when the fallback catalog search fails.
pub async fn purchase_hint(
base_url: &str,
opts: &PurchaseHintOpts,
) -> Result<Option<SourcePurchaseHint>>
Resolve a Libro.fm product link for a title, by ISBN first and then by title and author.
The bare-hint form of [purchase_answer]: its pick, without the
title-search records.
base_url- Libro.fm API origin.opts- ISBN, product id, title and authors to match.
As purchase_answer.
pub async fn purchase_answer(
base_url: &str,
opts: &PurchaseHintOpts,
) -> Result<PricedAnswer>
Resolve a Libro.fm product link for a title, with every for-sale listing a title search found.
- An ISBN (the query's
isbn, else an ISBN-shapedproduct_id) is looked up exactly. An ISBN lookup (PriceLookup::Isbn, which this store declares) stops there: the host asked whether Libro.fm sells that edition, so a miss answers nothing rather than another edition. - Otherwise the title and author are searched. Each of the first
TITLE_HINT_ROWS(5) rows is read in full (explore/audiobook_details, which also says whether it is for sale and its list price), and every for-sale row is returned as a priced record for the host to place. The first one is also the store's pick, so a host that reads only the hint still gets the best match.
With opts.with_price, the list price comes from
explore/audiobook_details (purchase_info.price, USD). An edition that
details report as not for sale is never offered, priced or not.
base_url- Libro.fm API origin.opts- ISBN, product id, title and authors to match, and how the host asks (lookup).
Returns SourceError::RateLimited
when Libro.fm asks to slow down. Any other failed ISBN lookup or title
search is logged and treated as no match, so an empty answer can also
mean the lookup failed.
pub fn parse_details(body: &[u8]) -> Result<LibroDetails>
Parses one explore/audiobook_details body.
Sans-IO so the unit tests drive the same code as the network path. The
list price (purchase_info.price) is copied onto the audiobook hit.
Returns an error when body is not JSON shaped like the details envelope.
pub fn parse_search_page(body: &[u8], limit: usize) -> Result<Vec<CatalogHit>>
Parses one catalog search response body into at most limit hits.
Sans-IO so the replay test and fuzz target drive the same code as the network path.
Returns an error when body is not JSON shaped like the search envelope.
pub const CATALOG_USER_AGENT: &str = "bookclerk/0.1.0 (+https://bookclerk.app)";
User agent for signed-out catalog calls: names Bookclerk and its site so Libro.fm can identify (and contact) the client.
Generated from crates/bookclerk-plugins/optional/source-libro at main · View as Markdown