bookclerk_discover

Development These docs follow the development version and change with every merge.

Last updated View as Markdown

Discovery: works graph, embeddings, recommendations, purchase hints, and requests.

Audience

Host binaries (bookclerkd, CLI) that build Discover shelves, catalog search, and wishlist ranking. Storefront plugins are not expected to depend on this crate directly.

See docs/ Discover / library product docs for operator-facing behavior.

Item Kind Summary
Embedder trait Produce dense vectors for recommendation / similarity search.
BranchAvailability struct One branch a title is available through.
CandidateFetchOptions struct Options for storefront candidate expansion.
SeedTitle struct One taste seed for storefront expansion: a book the subject has, or a title on their wishlist.
StorefrontCandidate struct A purchase candidate discovered from a storefront catalog (not owned locally).
CatalogSearchFilters struct Include / exclude filters applied after identity merge.
CatalogSearchHit struct One autocomplete / results-page hit (possibly spanning multiple storefronts).
CatalogSearchPage struct Paged catalog-search response.
CatalogSearchPageOpts struct Options for catalog_search_page.
CosineHit struct One cosine-similarity neighbor from an embedding query.
HashEmbedder struct Deterministic offline embedder for discovery similarity.
StoreEdition struct One storefront edition of a work (for multi-store purchase links).
WorkIdentity struct Bibliographic identity slice used for merge decisions.
MetadataEnrichOptions struct Pacing for one enrichment run.
FetchReport struct What one candidate fetch did.
OwnedIdentities struct Identifiers of every title the library holds, used to keep titles the library already has out of a subject's candidates and feed.
RankReport struct What one ranking did.
StoredSubjectFeed struct One subject's stored feed, ready for the page.
SubjectTaste struct One subject's taste: whose seeds Discover uses and what they read.
PurchaseHint struct A purchase / catalog availability hint (optionally priced at view time).
PurchaseHintsQuery struct Inputs for view-time catalog + pricing lookup.
PurchaseHintsResponse struct Priced catalog matches for one title, sorted best-first.
RankedQueueEntry struct Global wishlist queue entry ranked by overall/operator recommend taste + heavy wish-count weight (shared order; not per-viewer personalized).
RecommendOptions struct Tunables for recommend.
Recommendation struct One ranked recommendation (typically an unowned storefront title).
StoredRequestQueue struct The shared request queue as a read builds it.
DiscoverFeed struct Full Discover page payload: ordered shelves of personalized candidates.
DiscoverShelf struct One horizontal Discover row (series to finish, more by author, …).
ShelfKindInfo struct A shelf kind the operator can ignore (all offered by default).
ShelfTaste struct Taste context used to title and fill personalized shelves.
FillStoreLookups struct What a store declared about catalog-detail lookups, as a title-meta fill plan reads it.
TitleMeta struct Bibliographic fields suitable for an Audible-style detail panel.
TitleMetaQuery struct Query for public title metadata (Audnexus / Audible catalog).
TitleReview struct One Audible customer review for the title detail panel.
TitleReviewsPage struct One page of title reviews for infinite scroll.
TitleReviewsQuery struct Query for a page of Audible customer reviews.
PooledEdition struct One store edition a wish names, as placed in the shared pool.
FeedState enum How current a stored Discover feed is.
FillLookup enum One storefront catalog-detail lookup a title-meta fill can make.
TitleMetaQueryProblem enum Why a title-meta query was refused before any lookup ran.
join_branch_availability function Sets available_through on every card of feed.
join_search_branch_availability function Sets available_through on every hit of a catalog search page.
gather_storefront_candidates function Expand storefront catalogs from local taste seeds; drop already-owned ids.
select_taste_seeds function Pick local seed books for storefront expansion (finished / high-rated first).
catalog_search function Search every configured storefront catalog and merge by work identity.
catalog_search_page function Paged multi-store catalog browse (filters + sort + cursor).
catalog_search_with_field function Like catalog_search, optionally scoping storefront queries to a facet (author / narrator / series / genre). When language is set it is applied as a hard include filter (unknown/missing language still passes).
embed_dirty_works function Embed works whose text hash changed (or are missing), and drop the embeddings of works that no longer exist.
open_embedder function Opens the embedder the host uses while no plugin serves text embeddings.
text_for_work function Build the text blob embedded for a work.
candidate_map_key function Stable HashMap key for a storefront candidate (hard id, soft title+author, or source:product).
hard_work_key function Hard bibliographic key: canonical ISBN first, then ASIN.
identities_match function Whether two bibliographic identities refer to the same work.
merge_candidate_metadata function Merge storefront metadata into into, preferring filled fields / richer text.
merge_recommendation function Merge a scored recommendation into an existing card.
parse_series_index function Parse Audible/Chirp-style series indexes ("1", "1.5", "Book 2", "02").
push_edition function Appends a store edition when not already present (dedupes on source+product_id).
push_shelf_category function Append a stable shelf-kind tag (finish_series, author, …) if missing.
recommendation_map_key function Stable HashMap key for a recommendation card (same rules as work_map_key).
soft_work_key function Soft key from cleaned title + primary author (exact string match only).
work_map_key function Best stable map key for a recommendation / candidate.
works_match function Whether two titles should be treated as the same work.
enrich_books_from_metadata function Fills missing description, subjects, cover and language from the deployed metadata providers.
fetch_subject_candidates function Fetches one subject's storefront candidates and stores them store by store.
load_subject_taste function Loads one subject's taste.
rank_subject_feed function Ranks one subject's stored candidates into shelves and stores the feed.
refresh_subject_taste function Loads subject's taste from the library and stores it, so the next ranking reads it: what a candidate fetch does first, for a fetch that calls no storefront (storefront_candidates = false), whose taste events must still refresh the ranking.
stored_subject_feed function Reads one subject's stored feed, drops their hidden shelves and joins each card's catalog metadata from the candidate pool.
stored_subject_feed_state function Reads one subject's stored feed without joining its catalog metadata, for callers that need only whether it exists and when it was ranked.
best_purchase_hint function Pick the lowest-priced hint (ties keep earlier order). Unpriced sort after priced.
best_purchase_hint_preferring function Pick the offer the caller would actually pay least for.
format_money_label function Formats integer cents into a storefront-style money label for currency.
parse_money_label_to_cents function Parse $12.34 / 12.34 / FREE into cents.
purchase_hints_for function Look up purchase links via registered bookclerk_source::ContentSource::purchase_hint (no prices).
resolve_purchase_hints function Resolve every catalog match and attach live prices (view-time).
resolve_purchase_hints_batch function Resolve many purchase-hint queries at once (order preserved).
retain_card_recording function Drops live purchase hints that sell another recording than the card's.
retain_card_recordings function retain_card_recording for a batch of cards, with one pool read.
seed_purchase_hint function Seed a deterministic storefront URL from a known candidate (no remote I/O).
combine_wishlist_score function Combine local recommend taste with a heavy multi-user wishlist boost.
listening_engagement function Continuous engagement from a listening progress row (≈0.0–6.0).
rank_request_queue_taste function Ranks every entry of the shared request queue against household taste, for the discover_request_queue job to store.
recommend function Build ranked recommendations for the operator (or a specific external user).
recommend_feed function Personalized Discover feed (Netflix-style shelves) from the same candidate pool.
read_request_queue function Builds the ranked queue from the open requests and the stored ranking.
build_discover_feed function Partitions scored recommendations into Discover shelves.
flatten_feed function Flatten shelves into a unique score-sorted list (CLI / legacy).
shelf_is_disabled function Whether shelf_id matches an ignore entry (exact, kind prefix, or from_store).
shelf_kind_catalog function Shelf kinds Discover can emit (for config / UI ignore lists).
check_title_meta_query function Checks a title-meta query from a client before it is resolved.
plan_title_meta_fill function Plans the catalog-detail lookups that can fill query, in the order to try them.
resolve_title_meta function Resolve public metadata for a title detail dialog.
resolve_title_meta_batch function Resolve many title-meta queries with bounded concurrency (order preserved).
resolve_title_reviews function Resolve one page of Audible customer reviews for infinite scroll.
pool_wish_editions function Asks each store about the editions a wish names and records the answers in the shared pool.
record_wish_member_offers function Stores the member prices hints quote for editions already pooled.
EMBED_PAGE_WORKS constant Works read per page by embed_dirty_works; also the most texts one embedder call receives.
LOCAL_HASH_DIMENSIONS constant Numbers in one hash vector.
MODEL_LOCAL_HASH_V1 constant Model id stored beside hash vectors. They are never compared with a model's vectors.
DEFAULT_MAX_REQUESTS_PER_RUN constant Default cap on provider asks in one run.
METADATA_ENRICH_SOURCE_PREFIX constant enrich_source prefix marking a title filled by a metadata provider; the provider's plugin key follows it.
HOUSEHOLD_BLEND_WEIGHT constant How much a household book counts in a member's taste while it blends in, relative to one of their own.
OWN_TASTE_THRESHOLD constant Books and listens of their own a subject needs before the household's books stop blending into their taste.
STARTER_GENRES constant Genres browsed for a thin taste, in the order the stores are asked (the call budget may stop before the end).
STARTER_GENRE_MIN_SEEDS constant Seeds below which a fetch also browses each store's STARTER_GENRES, so a new library still gets shelves.
STORE_CALL_MAX_AGE constant How long a cached storefront answer is reused (the daily refresh).
STORE_CALL_TIMEOUT constant Longest one storefront call may take before its store moves on.
STORE_FETCH_DEADLINE constant How long one store may keep starting new calls in a fetch.
BATCH_DEADLINE constant Longest a batch waits for its lookups before answering with what has resolved. Under the daemon's 25 s route budget, so a slow store never turns a page of cards into one failed request.
BREAKER_OPEN_FOR constant How long a tripped store is skipped. After that, lookups ask it again, and BREAKER_TRIP_TIMEOUTS more timeouts in a row pause it again.
BREAKER_TRIP_TIMEOUTS constant Timeouts in a row after which a store's price lookups are skipped.
RATE_LIMIT_FIRST_PAUSE constant How long a store that asked to slow down without saying for how long is left alone the first time; each repeat doubles it.
RATE_LIMIT_MAX_PAUSE constant Longest pause a rate limit can grow to by doubling, and the most a store's own Retry-After is honored for.
WISH_COUNT_WEIGHT constant Per open wish on the global queue. Large enough that multi-user demand dominates typical local taste scores (~1–25) while recommend signals still order titles that share the same wish count.
REQUEST_QUEUE_MAX_AGE constant How old the stored ranking may get before a read asks for a new pass, so taste changes no event announces (a book removed, a rating edited) still reach the queue within a day.
SERIES_CAP constant Most titles of one series on a shelf that is not about series, so one long series cannot crowd the others out.
TITLE_META_BATCH_DEADLINE constant Longest a title-meta batch waits before answering with what resolved.
TITLE_META_MAX_STORE_EDITIONS constant Most store editions one title-meta query may name; the API rejects more (keep TitleMetaQuery::store_editions's doc in step).
MAX_WISH_EDITIONS constant Most store editions looked up for one wish. A wish names a few; the cap bounds what a crafted request can make the server fetch.

Re-exports

Traits

Embedder

pub trait Embedder: Send {
    fn model_id(&self) -> &str;
    fn dimensions(&self) -> usize;
    fn embed(&mut self, texts: &[String]) -> Result<Vec<Vec<f32>>, DiscoverError>;
}

Produce dense vectors for recommendation / similarity search.

Embedder::model_id

fn model_id(&self) -> &str

Stable embedding model id stored alongside vectors in SQLite.

Embedder::dimensions

fn dimensions(&self) -> usize

Length of each embedding vector produced by this backend.

Embedder::embed

fn embed(&mut self, texts: &[String]) -> Result<Vec<Vec<f32>>, DiscoverError>

Embeds each input text into a dense float vector of Self::dimensions length.

Errors

Returns an error when the operation fails.

Implemented by: HashEmbedder

Structs

BranchAvailability

pub struct BranchAvailability {
    pub work_id: String,
    pub node_id: String,
    pub owner_name: Option<String>,
    pub store: String,
    pub product_id: String,
}

One branch a title is available through.

Fields

  • work_id: This library's work the branch supplies: the work_id to send POST /api/branch-requests to ask the branch for it.
  • node_id: The branch node id.
  • owner_name: The branch owner's display name, for "available through Riley's branch"; absent when the owner has none.
  • store: The store the branch has the book from.
  • product_id: The store's product id of the branch's copy.

Implements: Clone, ComposeSchema, Debug, Deserialize<'de>, Eq, PartialEq, Serialize, ToSchema

CandidateFetchOptions

pub struct CandidateFetchOptions {
    pub region: String,
    pub seed_limit: usize,
    pub max_remote_calls: usize,
    pub include_audible: bool,
    pub include_libro: bool,
    pub include_chirp: bool,
    pub include_graphicaudio: bool,
    pub include_deals: bool,
    pub exclude_graphicaudio_series_sets: bool,
}

Options for storefront candidate expansion.

Fields

  • region: Marketplace / region code (us, uk, …) for catalog lookups.
  • seed_limit: Max local seed titles to expand from (finished / rated first).
  • max_remote_calls: Cap remote HTTP calls across all storefronts.
  • include_audible: Call bookclerk_source::ContentSource::expand_candidates on registered Audible.
  • include_libro: Call bookclerk_source::ContentSource::expand_candidates on registered Libro.fm.
  • include_chirp: Call bookclerk_source::ContentSource::expand_candidates on registered Chirp.
  • include_graphicaudio: Call bookclerk_source::ContentSource::expand_candidates on registered GraphicAudio.
  • include_deals: Fetch deals via bookclerk_source::ContentSource::list_deals on all registered sources.
  • exclude_graphicaudio_series_sets: When true, drop GraphicAudio Magento series-set SKUs from candidates. Default is false (sets are kept).

Implements: Clone, Debug, Default

SeedTitle

pub struct SeedTitle {
    pub seed: ExpandSeed,
    pub categories: Option<String>,
}

One taste seed for storefront expansion: a book the subject has, or a title on their wishlist.

Fields

  • seed: What the storefront is asked about.
  • categories: The seed's genres or subjects, copied onto candidates that lack their own.

SeedTitle::from_book

pub fn from_book(book: &TasteTitle, region: &str) -> Self

A seed from a library book.

SeedTitle::from_wish

pub fn from_wish(
    title: &str,
    authors: Option<String>,
    asin: Option<String>,
    isbn: Option<String>,
) -> Self

A seed from an open wishlist title (no store of its own; stores expand it by title, author and identifiers).

Implements: Clone, Debug

StorefrontCandidate

pub struct StorefrontCandidate {
    pub source: String,
    pub product_id: String,
    pub title: String,
    pub authors: Option<String>,
    pub narrators: Option<String>,
    pub series: Option<String>,
    pub series_index: Option<String>,
    pub asin: Option<String>,
    pub isbn: Option<String>,
    pub cover_url: Option<String>,
    pub seed_categories: Option<String>,
    pub origin: String,
    pub seed_title: Option<String>,
    pub starter_genre: Option<String>,
    pub store_editions: Vec<StoreEdition>,
    pub subtitle: Option<String>,
    pub description: Option<String>,
    pub publisher: Option<String>,
    pub length_minutes: Option<i64>,
    pub published_at: Option<String>,
    pub categories: Option<String>,
    pub language: Option<String>,
    pub price_cents: Option<i64>,
    pub currency: Option<String>,
    pub price_label: Option<String>,
    pub rating_overall: Option<f64>,
    pub rating_count: Option<i64>,
    pub is_abridged: Option<bool>,
    pub is_explicit: Option<bool>,
    pub store_rank: Option<u32>,
    pub work_id: Option<String>,
    pub expression_id: Option<String>,
    pub publisher_votes: Vec<String>,
}

A purchase candidate discovered from a storefront catalog (not owned locally).

Fields

  • source: Canonical storefront / plugin id (audible, libro, chirp, …).
  • product_id: Storefront-native product id (ASIN, ISBN, UUID, …).
  • title: Display title as shown on the storefront or library card.
  • authors: Comma-separated author names when the storefront provides them.
  • narrators: Comma-separated narrator names when known.
  • series: Series name when the title belongs to a named series.
  • series_index: Position within the series (e.g. 1, 1.5) when known.
  • asin: Audible / Amazon ASIN when this edition is sold on Audible.
  • isbn: Canonical ISBN-13 (or ISBN-10 normalized) when published.
  • cover_url: Public cover image URL when a storefront provided one.
  • seed_categories: Categories/subjects copied from the taste seed that produced this hit.
  • origin: How this candidate was found (related-to seed, author search, …).
  • seed_title: Owned-library title that seeded this related / similar candidate.
  • starter_genre: Starter genre this candidate was browsed from (display name), set only on hits of a starter-genre search for a thin taste.
  • store_editions: Known storefront editions of this work (including the primary source).
  • subtitle: Bibliographic extras from the storefront catalog payload (optional).
  • description: Publisher or storefront synopsis; may be truncated for embeddings.
  • publisher: Publisher imprint as reported by the catalog.
  • length_minutes: Audiobook runtime in whole minutes when known.
  • published_at: Publication date string from the catalog (ISO or storefront format).
  • categories: Genre / subject tags as a single delimited string when known.
  • language: BCP-47 / storefront language code (en, de, …) when known.
  • price_cents: List or deal price in integer cents of Self::currency.
  • currency: ISO 4217 currency code for price fields (USD, EUR, …).
  • price_label: Human-readable price string from the storefront (e.g. $14.95).
  • rating_overall: Community overall rating when a storefront provided one.
  • rating_count: Number of ratings backing Self::rating_overall when known.
  • is_abridged: Abridged flag when the storefront provided one.
  • is_explicit: Whether the storefront marks the edition explicit (adult) content; None when it did not say.
  • store_rank: The storefront's own 1-based search rank for this hit (its declared CatalogHit.rankHint); catalog search merges stores by it for relevance and popularity sorts. None when no store ranked it.
  • work_id: The work the pool resolved this listing into, when the candidate was read from the shared listing pool. Lets the ranking drop titles the library holds by work identity without resolving the title again.
  • expression_id: The expression (expressions.id) the pool resolved this listing into: two candidates with the same expression are the same recording sold by different stores, so one card carries both prices.
  • publisher_votes: The publisher each store listing merged into this row named, one entry per listing that named one, in arrival order. Empty until a second listing merges in; Self::publisher is then the name most of them agree on (see merge_candidate_metadata). Never sent.

Implements: Clone, Debug, Deserialize<'de>, Serialize

CatalogSearchFilters

pub struct CatalogSearchFilters {
    pub authors: Vec<String>,
    pub narrators: Vec<String>,
    pub series: Vec<String>,
    pub genres: Vec<String>,
    pub sources: Vec<String>,
    pub exclude_sources: Vec<String>,
    pub languages: Vec<String>,
    pub exclude_narrators: Vec<String>,
    pub min_rating: Option<f64>,
    pub min_length_minutes: Option<i64>,
    pub max_length_minutes: Option<i64>,
}

Include / exclude filters applied after identity merge.

Fields

  • authors: Comma-separated author names when the storefront provides them.
  • narrators: Comma-separated narrator names when known.
  • series: Series name when the title belongs to a named series.
  • genres: Genre labels from the catalog (comma-separated when multiple).
  • sources: Deduped storefront ids that contributed editions to this hit.
  • exclude_sources: Store ids to drop (any edition matching). Empty = no exclude.
  • languages: Normalized language codes (en, zh, …). When non-empty, only matching (or unknown/missing) languages pass.
  • exclude_narrators: Substring match on narrator strings (case-insensitive), e.g. Virtual Voice.
  • min_rating: Keep hits with rating_overall >= min or missing rating.
  • min_length_minutes: Inclusive lower bound on length_minutes; missing length passes.
  • max_length_minutes: Inclusive upper bound on length_minutes; missing length passes.

CatalogSearchFilters::is_empty

pub fn is_empty(&self) -> bool

Returns true when no include/exclude filters are set.

Implements: Clone, Debug, Default, Deserialize<'de>, Serialize

CatalogSearchHit

pub struct CatalogSearchHit {
    pub work_key: String,
    pub title: String,
    pub authors: Option<String>,
    pub narrators: Option<String>,
    pub series: Option<String>,
    pub series_index: Option<String>,
    pub asin: Option<String>,
    pub isbn: Option<String>,
    pub cover_url: Option<String>,
    pub cover_path: Option<String>,
    pub store_editions: Vec<StoreEdition>,
    pub sources: Vec<String>,
    pub subtitle: Option<String>,
    pub description: Option<String>,
    pub publisher: Option<String>,
    pub length_minutes: Option<i64>,
    pub published_at: Option<String>,
    pub genres: Option<String>,
    pub language: Option<String>,
    pub is_abridged: Option<bool>,
    pub is_explicit: Option<bool>,
    pub rating_overall: Option<f64>,
    pub rating_count: Option<i64>,
    pub price_cents: Option<i64>,
    pub purchase_hints: Vec<PurchaseHint>,
    pub available_through: Vec<BranchAvailability>,
}

One autocomplete / results-page hit (possibly spanning multiple storefronts).

Fields

  • work_key: Stable map key for this work (isbn:…, asin:…, or soft title+author).
  • title: Display title as shown on the storefront or library card.
  • authors: Comma-separated author names when the storefront provides them.
  • narrators: Comma-separated narrator names when known.
  • series: Series name when the title belongs to a named series.
  • series_index: Position within the series (e.g. 1, 1.5) when known.
  • asin: Audible / Amazon ASIN when this edition is sold on Audible.
  • isbn: Canonical ISBN-13 (or ISBN-10 normalized) when published.
  • cover_url: HTTPS URL for cover art when the catalog exposes one.
  • cover_path: Same-origin path of this cover's processed images, set by the daemon when cover_url is an https URL. Append /128 (thumbnail), /360 (card) or /full, so a client can show covers without loading cover_url from another site.
  • store_editions: Per-storefront edition ids that collapsed into this work card.
  • sources: Storefronts that matched (deduped source ids).
  • subtitle: Optional subtitle when the catalog distinguishes it from the title.
  • description: Publisher or storefront synopsis; may be truncated for embeddings.
  • publisher: Publisher imprint as reported by the catalog.
  • length_minutes: Audiobook runtime in whole minutes when known.
  • published_at: Publication date string from the catalog (ISO or storefront format).
  • genres: Genre labels from the catalog (comma-separated when multiple).
  • language: BCP-47 / storefront language code (en, de, …) when known.
  • is_abridged: When Some(true), the edition is marked abridged by the storefront.
  • is_explicit: When Some(true), a storefront marks the edition explicit (adult) content; None when none said.
  • rating_overall: Aggregate listener rating on the storefront's scale when known.
  • rating_count: Number of ratings backing Self::rating_overall when known.
  • price_cents: Catalog list/deal price in cents when the storefront provided it.
  • purchase_hints: Buy / open-in-store links with optional member vs list pricing.
  • available_through: Branches of this library that currently list this title, matched through a store listing the library already holds. Filled by the daemon after the search.
pub fn hide_prices_and_links(&mut self)

Removes the hit's price and its store links and prices.

CatalogSearchHit::unheld_item

pub fn unheld_item(&self) -> UnheldItem<'_>

The hit's metadata as a scope reads it.

Implements: Clone, ComposeSchema, Debug, Deserialize<'de>, Serialize, ToSchema

CatalogSearchPage

pub struct CatalogSearchPage {
    pub items: Vec<CatalogSearchHit>,
    pub page_size: usize,
    pub has_more: bool,
    pub next_cursor: Option<String>,
    pub sort: String,
    pub sort_dir: String,
}

Paged catalog-search response.

Fields

  • items: Ordered collection of child entries for this response.
  • page_size: Maximum number of items returned in this page.
  • has_more: When true, another page is available via Self::next_cursor.
  • next_cursor: Opaque cursor for the next page; omit or None when exhausted.
  • sort: Sort field applied to the merged result set.
  • sort_dir: Ascending or descending order for Self::sort.
pub fn hide_prices_and_links(&mut self)

Removes the prices and store links of every hit.

CatalogSearchPage::retain_in_scope

pub fn retain_in_scope(&mut self, scope: &WorkScope)

Drops every hit outside scope. The page keeps its cursor, so it can come back shorter than its size while more pages follow.

Implements: Clone, ComposeSchema, Debug, Deserialize<'de>, Serialize, ToSchema

CatalogSearchPageOpts

pub struct CatalogSearchPageOpts<'a> {
    pub query: &'a str,
    pub region: &'a str,
    pub page_size: usize,
    pub cursor: Option<&'a str>,
    pub sort: CatalogSearchSort,
    pub sort_dir: CatalogSortDir,
    pub field: Option<CatalogSearchField>,
    pub language: Option<&'a str>,
    pub all_languages: bool,
    pub filters: CatalogSearchFilters,
}

Options for catalog_search_page.

Fields

  • query: Free-text search string entered by the operator or SPA.
  • region: Marketplace / region code (us, uk, …) for catalog lookups.
  • page_size: Maximum number of items returned in this page.
  • cursor: Opaque pagination token from a previous page response.
  • sort: Sort field applied to the merged result set.
  • sort_dir: Ascending or descending order for Self::sort.
  • field: Optional catalog field scope (title, author, …) when searching one facet.
  • language: BCP-47 / storefront language code (en, de, …) when known.
  • all_languages: When true, do not default hard language filter from Self::language.
  • filters: Server-side include/exclude filters applied after identity merge.

Implements: Clone, Debug

CosineHit

pub struct CosineHit {
    pub target_id: String,
    pub score: f32,
}

One cosine-similarity neighbor from an embedding query.

Fields

  • target_id: Library entity id of the similar work (works.id).
  • score: Ranking score (higher is better); units are algorithm-specific.

Implements: Clone, Debug

HashEmbedder

pub struct HashEmbedder {
    /* private fields */
}

Deterministic offline embedder for discovery similarity.

It carries no meaning: two texts score alike only when they share words. It keeps the whole pipeline (hash → store → cosine) working while no plugin serves text embeddings.

HashEmbedder::new

pub fn new(dims: usize) -> Self

Creates a hash embedder with the given vector length (clamped to 8..=384).

Arguments
  • dims - Desired embedding length before clamping.
Returns

Embedder that maps text to deterministic unit vectors of length dims.

Implements: Debug, Default, Embedder

StoreEdition

pub struct StoreEdition {
    pub source: String,
    pub product_id: String,
}

One storefront edition of a work (for multi-store purchase links).

Fields

  • source: Canonical storefront / plugin id (audible, libro, chirp, …).
  • product_id: Storefront-native product id (ASIN, ISBN, UUID, …).

StoreEdition::new

pub fn new(source: impl Into<String>, product_id: impl Into<String>) -> Self

Creates a store edition from a storefront id and native product id.

Arguments
  • source - Storefront id or filesystem source path, depending on call site.
  • product_id - Storefront-native product id.
Returns

Newly constructed new value.

Implements: Clone, ComposeSchema, Debug, Deserialize<'de>, Eq, Hash, PartialEq, Serialize, ToSchema

WorkIdentity

pub struct WorkIdentity<'a> {
    pub asin: Option<&'a str>,
    pub isbn: Option<&'a str>,
    pub title: &'a str,
    pub authors: Option<&'a str>,
    pub series: Option<&'a str>,
    pub series_index: Option<&'a str>,
}

Bibliographic identity slice used for merge decisions.

Fields

  • asin: Audible / Amazon ASIN when this edition is sold on Audible.
  • isbn: Canonical ISBN-13 (or ISBN-10 normalized) when published.
  • title: Display title as shown on the storefront or library card.
  • authors: Comma-separated author names when the storefront provides them.
  • series: Series name when the title belongs to a named series.
  • series_index: Position within the series (e.g. 1, 1.5) when known.

WorkIdentity::new

pub fn new(
    asin: Option<&'a str>,
    isbn: Option<&'a str>,
    title: &'a str,
    authors: Option<&'a str>,
) -> Self

Creates a work identity from hard ids plus title and authors (no series yet).

Arguments
  • asin - Optional Audible / Amazon ASIN.
  • isbn - Optional ISBN (any punctuation; normalized internally).
  • title - Display title.
  • authors - Optional author string (comma-separated).
Returns

Newly constructed new value.

WorkIdentity::with_series

pub fn with_series(self, series: Option<&'a str>) -> Self

Sets the optional series name used in soft identity matching.

Arguments
  • series - Optional series name.
Returns

Updated Self for chaining.

WorkIdentity::with_series_index

pub fn with_series_index(self, series_index: Option<&'a str>) -> Self

Sets the optional series position used to avoid merging distinct volumes.

Arguments
  • series_index - Optional series position string.
Returns

Updated Self for chaining.

Implements: Clone, Copy, Debug

MetadataEnrichOptions

pub struct MetadataEnrichOptions {
    pub min_interval: Duration,
    pub max_requests: usize,
}

Pacing for one enrichment run.

Fields

  • min_interval: Pause before each provider ask.
  • max_requests: Most provider asks in one run; titles past the cap wait for the next run.

Implements: Clone, Debug, Default

FetchReport

pub struct FetchReport {
    pub seeds: usize,
    pub stores_saved: usize,
    pub candidates: usize,
    pub stores_failed: Vec<String>,
    pub priced: usize,
}

What one candidate fetch did.

Fields

  • seeds: Seeds the subject's taste offered (books, then wishlist titles).
  • stores_saved: Stores whose answers were stored.
  • candidates: Candidates stored across those stores.
  • stores_failed: Stores whose fetch failed outright, by plugin id.
  • priced: Candidates that carry a price from the fetch, across stores.

Implements: Clone, Debug, Default, Eq, PartialEq

OwnedIdentities

pub struct OwnedIdentities {
    pub asins: HashSet<String>,
    pub isbns: HashSet<String>,
    pub products: HashSet<String>,
}

Identifiers of every title the library holds, used to keep titles the library already has out of a subject's candidates and feed.

Fields

  • asins: Upper-cased ASINs.
  • isbns: Canonical ISBN-13s.
  • products: source:product_id keys and bare product ids.

Implements: Clone, Debug, Default, Eq, PartialEq

RankReport

pub struct RankReport {
    pub scope: SeedScope,
    pub shelves: usize,
    pub candidates: usize,
    pub cards: usize,
    pub stored_bytes: usize,
}

What one ranking did.

Fields

  • scope: Seeds the feed was ranked against.
  • shelves: Shelves stored.
  • candidates: Stored candidates read.
  • cards: Cards on the stored shelves, after any trimming to fit the budget.
  • stored_bytes: Bytes of the stored feed as the database counts it (an escaped JSON string), at most the 192 KiB stored-feed budget.

Implements: Clone, Debug, Eq, PartialEq

StoredSubjectFeed

pub struct StoredSubjectFeed {
    pub feed: DiscoverFeed,
    pub scope: SeedScope,
    pub computed_at: DateTime<Utc>,
    pub candidates_fetched_at: Option<DateTime<Utc>>,
}

One subject's stored feed, ready for the page.

Fields

  • feed: The shelves, without the subject's hidden ones.
  • scope: Seeds the feed was ranked from.
  • computed_at: When it was ranked.
  • candidates_fetched_at: Newest storefront fetch it used, when any.

Implements: Clone, Debug

SubjectTaste

pub struct SubjectTaste {
    pub scope: SeedScope,
    pub books: Vec<TasteTitle>,
    pub weights: HashMap<String, f64>,
    pub listening: Vec<ListeningSignal>,
    pub wishlist: Vec<SeedTitle>,
    pub wish_titles: Vec<String>,
    pub linked_sources: HashSet<String>,
    pub owned: OwnedIdentities,
}

One subject's taste: whose seeds Discover uses and what they read.

Fields

  • scope: Whether the taste is the subject's own or the household's.
  • books: Books whose finishes, ratings, series and authors shape the taste: the subject's own, then the household's blended in while the subject's own are fewer than OWN_TASTE_THRESHOLD.
  • weights: How much each book in books counts; a blended household book is listed at HOUSEHOLD_BLEND_WEIGHT, the subject's own count in full.
  • listening: The subject's listening rows (all rows for the household). While household books blend in, the household's rows for those books are added too, and count at their book's weight.
  • wishlist: The subject's open wishlist titles, newest first, used as extra seeds.
  • wish_titles: Display titles of wishlist, newest first.
  • linked_sources: Lowercase storefront ids the subject has an account with.
  • owned: Identifiers of every title the library holds, read with the taste so a subject job reads the library once.

Implements: Clone, Debug

PurchaseHint

pub struct PurchaseHint {
    pub source: String,
    pub product_id: String,
    pub title: Option<String>,
    pub url: Option<String>,
    pub price_cents: Option<i64>,
    pub currency: Option<String>,
    pub price_label: Option<String>,
    pub list_price_cents: Option<i64>,
    pub list_price_label: Option<String>,
    pub member_price_cents: Option<i64>,
    pub member_price_label: Option<String>,
}

A purchase / catalog availability hint (optionally priced at view time).

Fields

  • source: Canonical storefront / plugin id (audible, libro, chirp, …).
  • product_id: Storefront-native product id (ASIN, ISBN, UUID, …).
  • title: Display title as shown on the storefront or library card.
  • url: Absolute HTTPS URL.
  • price_cents: Primary / best known sell price in minor units (prefer member when dual). 0 = free.
  • currency: ISO 4217 currency code for price fields (USD, EUR, …).
  • price_label: Display string from the store ($2.99, FREE, …).
  • list_price_cents: Non-member / list price in integer cents when known.
  • list_price_label: Human-readable list price from the storefront.
  • member_price_cents: Member / credit price in integer cents when known.
  • member_price_label: Human-readable member price from the storefront.
pub fn hide_price_and_link(&mut self)

Removes the hint's store link and every price it carries.

pub fn link(
    source: impl Into<String>,
    product_id: impl Into<String>,
    title: Option<String>,
    url: Option<String>,
) -> Self

URL-only catalog link (no price yet).

Arguments
  • source - Storefront id or filesystem source path, depending on call site.
  • product_id - Storefront-native product id.
  • title - Display title.
  • url - Absolute URL being checked or opened.
Returns

Updated Self for chaining.

Implements: Clone, ComposeSchema, Debug, Default, Deserialize<'de>, Eq, PartialEq, Serialize, ToSchema

PurchaseHintsQuery

pub struct PurchaseHintsQuery {
    pub title: String,
    pub authors: Option<String>,
    pub asin: Option<String>,
    pub isbn: Option<String>,
    pub candidate_source: Option<String>,
    pub candidate_product_id: Option<String>,
    pub store_editions: Vec<StoreEdition>,
    pub region: Option<String>,
    pub preferred_sources: Vec<String>,
}

Inputs for view-time catalog + pricing lookup.

Fields

  • title: Display title as shown on the storefront or library card.
  • authors: Comma-separated author names when the storefront provides them.
  • asin: Audible / Amazon ASIN when this edition is sold on Audible.
  • isbn: Canonical ISBN-13 (or ISBN-10 normalized) when published.
  • candidate_source: Storefront id of the edition that produced this card.
  • candidate_product_id: Storefront product id of the edition that produced this card.
  • store_editions: Known storefront editions already on the recommendation card.
  • region: Marketplace / region code (us, uk, …) for catalog lookups.
  • preferred_sources: Storefronts the caller has linked accounts for. Treated as member pricing when picking best; other stores are compared at list / non-member price. Every catalog match is still returned in hints.

Implements: Clone, ComposeSchema, Debug, Default, Deserialize<'de>, Serialize, ToSchema

PurchaseHintsResponse

pub struct PurchaseHintsResponse {
    pub hints: Vec<PurchaseHint>,
    pub best: Option<PurchaseHint>,
    pub incomplete: bool,
}

Priced catalog matches for one title, sorted best-first.

Fields

  • hints: Resolved purchase hints for this query.
  • best: Lowest-priced hint (or first catalog hit when no prices resolved).
  • incomplete: True when the batch deadline cut this lookup short (the hints are the query's trusted seeds alone), or when the hints could not be checked against the card's recording in time: a client should not keep the answer and asks again later. Omitted (false) for a finished lookup.
pub fn hide_prices_and_links(&mut self)

Removes the store links and prices of every hint, best included.

Implements: Clone, ComposeSchema, Debug, Default, Deserialize<'de>, Serialize, ToSchema

RankedQueueEntry

pub struct RankedQueueEntry {
    pub work_key: String,
    pub work_id: String,
    pub title: String,
    pub authors: Option<String>,
    pub asin: Option<String>,
    pub isbn: Option<String>,
    pub cover_url: Option<String>,
    pub cover_path: Option<String>,
    pub wish_count: i64,
    pub wishers: Vec<QueueWisher>,
    pub sample_uuids: Vec<String>,
    pub first_requested_at: DateTime<Utc>,
    pub last_requested_at: DateTime<Utc>,
    pub score: f64,
    pub taste_score: f64,
    pub reasons: Vec<String>,
}

Global wishlist queue entry ranked by overall/operator recommend taste + heavy wish-count weight (shared order; not per-viewer personalized).

Fields

  • work_key: Stable map key for this work (isbn:…, asin:…, or soft title+author).
  • work_id: The work every wish of this entry is for. Wishes for one work are one entry even when their work_keys differ, so a client matches its own wishes on this id first and on work_key otherwise.
  • title: Display title as shown on the storefront or library card.
  • authors: Comma-separated author names when the storefront provides them.
  • asin: Audible / Amazon ASIN when this edition is sold on Audible.
  • isbn: Canonical ISBN-13 (or ISBN-10 normalized) when published.
  • cover_url: HTTPS URL for cover art when the catalog exposes one.
  • cover_path: Same-origin path of this cover's processed images, set by the daemon when cover_url is an https URL. Append /128 (thumbnail), /360 (card) or /full, so a client can show covers without loading cover_url from another site.
  • wish_count: Number of distinct users who wishlisted this title.
  • wishers: Distinct people who have this title on an open wishlist.
  • sample_uuids: Sample Bookclerk user UUIDs who requested this title (privacy-capped).
  • first_requested_at: UTC timestamp of the earliest wishlist request for this work.
  • last_requested_at: UTC timestamp of the latest wishlist request for this work.
  • score: Final rank score (taste_score + wish_count * WISH_COUNT_WEIGHT).
  • taste_score: Local taste / embedding component before the wish-count boost.
  • reasons: Short human-readable explanations for why this item was ranked here.

Implements: Clone, ComposeSchema, Debug, Deserialize<'de>, Serialize, ToSchema

RecommendOptions

pub struct RecommendOptions {
    pub limit: usize,
    pub embedding_model: String,
    pub region: String,
    pub include_purchase_hints: bool,
    pub external_user_id: Option<String>,
    pub include_listening: bool,
    pub listening_providers: Vec<String>,
    pub fetch_storefront_candidates: bool,
    pub storefront_seed_limit: usize,
    pub storefront_max_remote_calls: usize,
    pub exclude_graphicaudio_series_sets: bool,
    pub disabled_shelves: Vec<String>,
    pub embeddings_enabled: bool,
}

Tunables for recommend.

Fields

  • limit: Maximum number of recommendations to return.
  • embedding_model: Model id of the vectors compared for similarity (local-hash-v1, …).
  • region: Marketplace / region code (us, uk, …) for catalog lookups.
  • include_purchase_hints: When true, attach buy links to each recommendation.
  • external_user_id: When set, only listening rows for this external user influence ranking. Provider-agnostic — any integration that synced that user id.
  • include_listening: When false, ignore listening_progress entirely (owned-library taste only). Listening is always optional: empty/missing progress simply adds no signal.
  • listening_providers: When non-empty, only use listening rows from these integration ids (audiobookshelf, plugin ids, …). Empty = all providers.
  • fetch_storefront_candidates: Pull unowned titles from storefront catalogs (the primary path).
  • storefront_seed_limit: Max owned titles used as storefront related-search seeds.
  • storefront_max_remote_calls: Hard cap on outbound catalog calls during recommend.
  • exclude_graphicaudio_series_sets: Drop GraphicAudio Magento series-set SKUs from discovery candidates.
  • disabled_shelves: Shelf kinds / ids to hide (finish_series, author, genre, from_store, …). Empty = offer every shelf Discover can build.
  • embeddings_enabled: When false, skip embedding similarity and use heuristic ranking only.

Implements: Clone, Debug, Default

Recommendation

pub struct Recommendation {
    pub work_id: Option<String>,
    pub expression_id: Option<String>,
    pub title: String,
    pub authors: Option<String>,
    pub narrators: Option<String>,
    pub series: Option<String>,
    pub series_index: Option<String>,
    pub asin: Option<String>,
    pub isbn: Option<String>,
    pub score: f64,
    pub reasons: Vec<String>,
    pub purchase_hints: Vec<PurchaseHint>,
    pub from_request: bool,
    pub request_uuid: Option<String>,
    pub candidate_source: Option<String>,
    pub candidate_product_id: Option<String>,
    pub store_editions: Vec<StoreEdition>,
    pub seed_categories: Option<String>,
    pub categories: Vec<String>,
    pub work_key: String,
    pub cover_url: Option<String>,
    pub cover_path: Option<String>,
    pub subtitle: Option<String>,
    pub description: Option<String>,
    pub publisher: Option<String>,
    pub length_minutes: Option<i64>,
    pub published_at: Option<String>,
    pub genres: Option<String>,
    pub language: Option<String>,
    pub is_explicit: Option<bool>,
    pub wishers: Vec<QueueWisher>,
    pub wish_count: i64,
    pub seed_title: Option<String>,
    pub starter_genre: Option<String>,
    pub available_through: Vec<BranchAvailability>,
}

One ranked recommendation (typically an unowned storefront title).

Fields

  • work_id: Library works.id of the work the card's edition belongs to, when the library's data model places it (a wish, or a store listing from the shared listing pool). Cards for one work are one card.
  • expression_id: expressions.id of the card's edition, when known: the recording (or text) it is. Only listings of this expression add prices to the card. Used while ranking; never stored or sent.
  • title: Display title as shown on the storefront or library card.
  • authors: Comma-separated author names when the storefront provides them.
  • narrators: Comma-separated narrator names when known.
  • series: Series name when the title belongs to a named series.
  • series_index: Position within the series (e.g. 1, 1.5) when known.
  • asin: Audible / Amazon ASIN when this edition is sold on Audible.
  • isbn: Canonical ISBN-13 (or ISBN-10 normalized) when published.
  • score: Ranking score (higher is better); units are algorithm-specific.
  • reasons: Short human-readable explanations for why this item was ranked here.
  • purchase_hints: Buy / open-in-store links with optional member vs list pricing.
  • from_request: True when sourced from an open title request rather than storefront discovery.
  • request_uuid: Wishlist / title-request UUID when this card came from a request.
  • candidate_source: Storefront that proposed this title (audible, libro, …).
  • candidate_product_id: Storefront product id of the edition that produced this card.
  • store_editions: All known storefront editions (for multi-store purchase links).
  • seed_categories: Categories/subjects copied from the taste seed that produced this hit.
  • categories: Stable shelf-kind tags for prefs (finish_series, author, chirp_deals, …). Dynamic shelf titles stay in build_discover_feed; membership uses these.
  • work_key: Stable bibliographic key for wishlist / merge (isbn: / asin: / soft:…).
  • cover_url: Cover art URL when known from a storefront catalog hit or wishlist row.
  • cover_path: Same-origin path of this cover's processed images, set by the daemon when cover_url is an https URL. Append /128 (thumbnail), /360 (card) or /full, so a client can show covers without loading cover_url from another site.
  • subtitle: Optional bibliographic extras from storefront catalog / Audnexus.
  • description: Publisher or storefront synopsis; may be truncated for embeddings.
  • publisher: Publisher imprint as reported by the catalog.
  • length_minutes: Audiobook runtime in whole minutes when known.
  • published_at: Publication date string from the catalog (ISO or storefront format).
  • genres: Candidate genres (not taste-seed seed_categories).
  • language: BCP-47 / storefront language code (en, de, …) when known.
  • is_explicit: When Some(true), a storefront marks the edition explicit (adult) content; None when none said (a wishlist entry says nothing).
  • wishers: Distinct people who have this title on an open wishlist.
  • wish_count: Number of distinct users who wishlisted this title (may exceed wishers.len()).
  • seed_title: Title of the book or wish the storefront was asked about to find this card, when it came from such an expansion.
  • starter_genre: Starter genre this card was browsed from while the taste was thin.
  • available_through: Branches of this library that currently list this title (they answered a catalog lookup for its work). Filled when the feed is read, never stored with it.
pub fn hide_prices_and_links(&mut self)

Removes the card's store links and prices.

Recommendation::unheld_item

pub fn unheld_item(&self) -> UnheldItem<'_>

The card's metadata as a scope reads it.

Implements: Clone, ComposeSchema, Debug, Default, Deserialize<'de>, Serialize, ToSchema

StoredRequestQueue

pub struct StoredRequestQueue {
    pub entries: Vec<RankedQueueEntry>,
    pub stale: bool,
}

The shared request queue as a read builds it.

Fields

  • entries: Open entries the library does not hold, best first.
  • stale: True when the stored ranking is missing an entry or older than REQUEST_QUEUE_MAX_AGE, so the caller should queue a ranking pass.

Implements: Clone, Debug, Default

DiscoverFeed

pub struct DiscoverFeed {
    pub shelves: Vec<DiscoverShelf>,
    pub shelf_kinds: Vec<ShelfKindInfo>,
    pub state: Option<FeedState>,
    pub computed_at: Option<String>,
}

Full Discover page payload: ordered shelves of personalized candidates.

Fields

  • shelves: Ordered horizontal shelves that make up the Discover page.
  • shelf_kinds: Catalog of shelf kinds for ignore prefs (empty disabled_shelves = all on).
  • state: Whether these are the caller's current shelves, set by the daemon's read of the stored feed. Absent in a stored feed and from the CLI.
  • computed_at: RFC 3339 time the shelves were ranked; absent while state is preparing.
pub fn hide_prices_and_links(&mut self)

Removes the store links and prices of every card on every shelf.

DiscoverFeed::retain_in_scope

pub fn retain_in_scope(&mut self, scope: &WorkScope)

Drops every card outside scope, then every shelf left empty.

Implements: Clone, ComposeSchema, Debug, Default, Deserialize<'de>, Serialize, ToSchema

DiscoverShelf

pub struct DiscoverShelf {
    pub id: String,
    pub title: String,
    pub subtitle: Option<String>,
    pub items: Vec<Recommendation>,
}

One horizontal Discover row (series to finish, more by author, …).

Fields

  • id: Stable identifier for this item.
  • title: Display title as shown on the storefront or library card.
  • subtitle: Optional subtitle when the catalog distinguishes it from the title.
  • items: Ordered collection of child entries for this response.

Implements: Clone, ComposeSchema, Debug, Deserialize<'de>, Serialize, ToSchema

ShelfKindInfo

pub struct ShelfKindInfo {
    pub id: String,
    pub label: String,
}

A shelf kind the operator can ignore (all offered by default).

Fields

  • id: Stable kind id (finish_series, author, genre, from_store, …).
  • label: Operator-visible label for this account or item.

Implements: Clone, ComposeSchema, Debug, Deserialize<'de>, Serialize, ToSchema

ShelfTaste

pub struct ShelfTaste {
    pub authors: HashMap<String, (String, f64)>,
    pub narrators: HashMap<String, (String, f64)>,
    pub categories: HashMap<String, (String, f64)>,
    pub seed_authors_by_title: HashMap<String, Vec<String>>,
    pub owned_sources: HashSet<String>,
    pub wish_titles: Vec<String>,
    pub linked_sources: HashSet<String>,
}

Taste context used to title and fill personalized shelves.

Fields

  • authors: Lowercase author → (display name, weight).
  • narrators: Lowercase narrator → (display name, weight).
  • categories: Lowercase category/subject → (display name, weight).
  • seed_authors_by_title: Seed title (lowercase) → authors on that seed (display).
  • owned_sources: Storefronts represented in the owned library (audible, libro, …).
  • wish_titles: Titles on the subject's own open wishlist, newest first, that name the "Because you wishlisted" shelves.
  • linked_sources: Lowercase storefront ids the subject has an account with, compared at member price when a card is placed on a store shelf.

Implements: Clone, Debug, Default, Deserialize<'de>, PartialEq, Serialize

FillStoreLookups

pub struct FillStoreLookups {
    pub plugin_key: String,
    pub by_product_id: bool,
    pub by_isbn: bool,
}

What a store declared about catalog-detail lookups, as a title-meta fill plan reads it.

Fields

  • plugin_key: The store's plugin key; two lookups for the same key and id are one.
  • by_product_id: The store declared detailByProductId.
  • by_isbn: The store declared detailByIsbn.

Implements: Clone, Debug, Eq, PartialEq

TitleMeta

pub struct TitleMeta {
    pub asin: Option<String>,
    pub title: Option<String>,
    pub subtitle: Option<String>,
    pub authors: Option<String>,
    pub narrators: Option<String>,
    pub series: Option<String>,
    pub series_index: Option<String>,
    pub isbn: Option<String>,
    pub cover_url: Option<String>,
    pub cover_path: Option<String>,
    pub description: Option<String>,
    pub publisher: Option<String>,
    pub length_minutes: Option<i64>,
    pub published_at: Option<String>,
    pub categories: Option<String>,
    pub language: Option<String>,
    pub is_abridged: Option<bool>,
    pub rating_overall: Option<f64>,
    pub rating_performance: Option<f64>,
    pub rating_story: Option<f64>,
    pub rating_count: Option<i64>,
    pub review_count: Option<i64>,
    pub reviews: Vec<TitleReview>,
}

Bibliographic fields suitable for an Audible-style detail panel.

Fields

  • asin: Audible / Amazon ASIN when this edition is sold on Audible.
  • title: Display title as shown on the storefront or library card.
  • subtitle: Optional subtitle when the catalog distinguishes it from the title.
  • authors: Comma-separated author names when the storefront provides them.
  • narrators: Comma-separated narrator names when known.
  • series: Series name when the title belongs to a named series.
  • series_index: Position within the series (e.g. 1, 1.5) when known.
  • isbn: Canonical ISBN-13 (or ISBN-10 normalized) when published.
  • cover_url: HTTPS URL for cover art when the catalog exposes one.
  • cover_path: Same-origin path of this cover's processed images, set by the daemon when cover_url is an https URL. Append /128 (thumbnail), /360 (card) or /full, so a client can show covers without loading cover_url from another site.
  • description: Publisher or storefront synopsis; may be truncated for embeddings.
  • publisher: Publisher imprint as reported by the catalog.
  • length_minutes: Audiobook runtime in whole minutes when known.
  • published_at: Publication date string from the catalog (ISO or storefront format).
  • categories: Genre / subject tags as a single delimited string when known.
  • language: BCP-47 / storefront language code (en, de, …) when known.
  • is_abridged: Some(true) abridged / Some(false) unabridged when the storefront said so.
  • rating_overall: Audible community overall rating (0–5).
  • rating_performance: Narration / performance sub-score when the storefront splits ratings.
  • rating_story: Story / content sub-score when the storefront splits ratings.
  • rating_count: Count of star ratings (Audible num_ratings).
  • review_count: Count of written reviews (Audible num_reviews).
  • reviews: Deprecated: reviews load via /api/discover/title-reviews. Kept empty for older clients; prefer the paginated reviews endpoint.

Implements: Clone, ComposeSchema, Debug, Deserialize<'de>, Serialize, ToSchema

TitleMetaQuery

pub struct TitleMetaQuery {
    pub title: String,
    pub authors: Option<String>,
    pub asin: Option<String>,
    pub isbn: Option<String>,
    pub narrators: Option<String>,
    pub length_minutes: Option<i64>,
    pub region: String,
    pub store_editions: Vec<StoreEdition>,
}

Query for public title metadata (Audnexus / Audible catalog).

Fields

  • title: Display title as shown on the storefront or library card.
  • authors: Comma-separated author names when the storefront provides them.
  • asin: Audible / Amazon ASIN when this edition is sold on Audible.
  • isbn: Canonical ISBN-13 (or ISBN-10 normalized) when published.
  • narrators: Comma-separated narrator names when known.
  • length_minutes: Audiobook runtime in whole minutes when known.
  • region: Marketplace / region code (us, uk, …) for catalog lookups.
  • store_editions: Store editions that listed this title (the search hit's or card's store_editions), at most 16. A sparse record is filled from each of these stores that declared detailByProductId, by the product id it gave the title, before the stores that declared detailByIsbn are asked by ISBN.

Implements: Clone, ComposeSchema, Debug, Deserialize<'de>, Serialize, ToSchema

TitleReview

pub struct TitleReview {
    pub id: Option<String>,
    pub title: Option<String>,
    pub body: String,
    pub author_name: Option<String>,
    pub overall_rating: Option<i64>,
    pub performance_rating: Option<i64>,
    pub story_rating: Option<i64>,
    pub submitted_at: Option<String>,
}

One Audible customer review for the title detail panel.

Fields

  • id: Stable identifier for this item.
  • title: Display title as shown on the storefront or library card.
  • body: Full review text from the storefront.
  • author_name: Display name of the review author on the storefront.
  • overall_rating: Overall star rating for this review when present.
  • performance_rating: Narration sub-rating for this review when present.
  • story_rating: Story sub-rating for this review when present.
  • submitted_at: When the review was submitted (storefront timestamp string).

Implements: Clone, ComposeSchema, Debug, Deserialize<'de>, From<CatalogReview>, Serialize, ToSchema

TitleReviewsPage

pub struct TitleReviewsPage {
    pub asin: String,
    pub page: u32,
    pub page_size: u32,
    pub has_more: bool,
    pub sort_by: String,
    pub reviews: Vec<TitleReview>,
}

One page of title reviews for infinite scroll.

Fields

  • asin: Audible / Amazon ASIN when this edition is sold on Audible.
  • page: 1-based page index for this reviews / list request.
  • page_size: Maximum number of items returned in this page.
  • has_more: When true, another page is available by incrementing Self::page.
  • sort_by: Remote sort key for reviews (MostHelpful or MostRecent, as applied).
  • reviews: Review rows on this page.

Implements: Clone, ComposeSchema, Debug, Deserialize<'de>, Serialize, ToSchema

TitleReviewsQuery

pub struct TitleReviewsQuery {
    pub asin: String,
    pub region: String,
    pub page: u32,
    pub page_size: u32,
    pub sort_by: String,
}

Query for a page of Audible customer reviews.

Fields

  • asin: Audible / Amazon ASIN when this edition is sold on Audible.
  • region: Marketplace / region code (us, uk, …) for catalog lookups.
  • page: 1-based page index.
  • page_size: Page size (clamped server-side to 1..=20).
  • sort_by: MostHelpful (default) or MostRecent.

Implements: Clone, ComposeSchema, Debug, Deserialize<'de>, Serialize, ToSchema

PooledEdition

pub struct PooledEdition {
    pub source: String,
    pub product_id: String,
    pub listing_id: String,
    pub work: Option<WishWork>,
}

One store edition a wish names, as placed in the shared pool.

Fields

  • source: Storefront plugin id the wish named (libro), lower-cased.
  • product_id: The store's product id the wish named.
  • listing_id: The store_listings row the store's answer resolved to.
  • work: The work and edition that listing resolved to, when it has a work.

Implements: Clone, Debug, Eq, PartialEq

Enums

FeedState

pub enum FeedState {
    Ready,
    Refreshing,
    Preparing,
}

How current a stored Discover feed is.

Variants

  • Ready: The stored shelves are current.
  • Refreshing: Stored shelves are shown while a newer fetch or ranking is queued.
  • Preparing: No shelves are stored yet; a fetch is queued and the page shows placeholders.

Implements: Clone, ComposeSchema, Copy, Debug, Deserialize<'de>, Eq, PartialEq, Serialize, ToSchema

FillLookup

pub enum FillLookup {
    Product(String),
    Isbn(String),
}

One storefront catalog-detail lookup a title-meta fill can make.

Variants

  • Product: The store's own product id for an edition it listed (detailByProductId).
  • Isbn: The title's ISBN (detailByIsbn).

FillLookup::kind

pub fn kind(&self) -> &'static str

What kind of lookup this is (product or isbn), for logs that must not name the title.

FillLookup::key

pub fn key(&self) -> &str

The id this lookup asks the store for (a product id or an ISBN).

Implements: Clone, Debug, Eq, PartialEq

TitleMetaQueryProblem

pub enum TitleMetaQueryProblem {
    TooManyStoreEditions,
    NothingToLookUp,
}

Why a title-meta query was refused before any lookup ran.

Variants

  • TooManyStoreEditions: The query named more than TITLE_META_MAX_STORE_EDITIONS store editions.
  • NothingToLookUp: The query's title, ASIN and ISBN are all blank.

Implements: Clone, Copy, Debug, Display, Eq, PartialEq

Functions

join_branch_availability

pub async fn join_branch_availability(
    library: &LibraryStore,
    feed: &mut DiscoverFeed,
    pool: Option<&CandidatePool>,
) -> Result<(), DiscoverError>

Sets available_through on every card of feed.

A card's work is its work_id, or else the work of the first of its store editions the candidate pool holds. Cards with no work, or whose work no branch currently lists, get an empty list.

Arguments

  • library - The library whose branch answers are read.
  • feed - The feed as read for one subject.
  • pool - The subject's candidate pool, when it was read.

Errors

Returns the library read error.

join_search_branch_availability

pub async fn join_search_branch_availability(
    library: &LibraryStore,
    hits: &mut [CatalogSearchHit],
    plugin_key_of: impl Fn(&str) -> Option<String>,
) -> Result<(), DiscoverError>

Sets available_through on every hit of a catalog search page.

A hit's work is the work of the first of its store editions the shared listing pool holds (an owned, wished or recommended book's listing). A hit the pool knows nothing about gets an empty list.

Arguments

  • library - The library whose pool and branch answers are read.
  • hits - The page's hits.
  • plugin_key_of - The PluginKey a storefront id's listings are pooled under, or None for a source that is not deployed.

Errors

Returns the library read error.

gather_storefront_candidates

pub async fn gather_storefront_candidates(
    _library: &LibraryStore,
    registry: &SourceRegistry,
    seeds: &[TasteTitle],
    owned_asins: &HashSet<String>,
    owned_isbns: &HashSet<String>,
    owned_product_keys: &HashSet<String>,
    opts: &CandidateFetchOptions,
) -> Result<Vec<StorefrontCandidate>, DiscoverError>

Expand storefront catalogs from local taste seeds; drop already-owned ids.

Arguments

  • library - Open library store used for reads/writes.
  • registry - Configured content-source or integration registry.
  • seeds - seeds input for this call.
  • owned_asins - String owned_asins for this call.
  • owned_isbns - String owned_isbns for this call.
  • owned_product_keys - String owned_product_keys for this call.
  • opts - Options struct for this operation.

Returns

On success, the inner Vec<StorefrontCandidate> value.

Errors

Returns an error when the underlying I/O, parse, network, or store operation fails.

select_taste_seeds

pub fn select_taste_seeds(
    books: &[TasteTitle],
    listening_engagement_by_uuid: &HashMap<String, f64>,
) -> Vec<TasteTitle>

Pick local seed books for storefront expansion (finished / high-rated first).

Arguments

  • books - books input for this call.
  • listening_engagement_by_uuid - String listening_engagement_by_uuid for this call.

Returns

Collected results (may be empty).

pub async fn catalog_search(
    registry: &SourceRegistry,
    query: &str,
    region: &str,
    limit: usize,
) -> Result<Vec<CatalogSearchHit>, DiscoverError>

Search every configured storefront catalog and merge by work identity.

Arguments

  • registry - Configured content-source or integration registry.
  • query - Query vector or free-text search string.
  • region - Marketplace / region code (us, uk, …).
  • limit - Maximum number of results to return.

Returns

On success, the inner Vec<CatalogSearchHit> value.

Errors

Returns an error when the underlying I/O, parse, network, or store operation fails.

catalog_search_page

pub async fn catalog_search_page(
    registry: &SourceRegistry,
    pool: Option<&LibraryStore>,
    opts: CatalogSearchPageOpts<'_>,
) -> Result<CatalogSearchPage, DiscoverError>

Paged multi-store catalog browse (filters + sort + cursor).

Arguments

  • registry - Configured content-source or integration registry.
  • pool - The library whose shared listing pool names the recording each hit is, so one recording sold by several stores is one row; None merges hits only by shared ISBN, ASIN or store product.
  • opts - Options struct for this operation.

Returns

On success, the inner CatalogSearchPage value.

Errors

Returns an error when the underlying I/O, parse, network, or store operation fails.

catalog_search_with_field

pub async fn catalog_search_with_field(
    registry: &SourceRegistry,
    query: &str,
    region: &str,
    limit: usize,
    field: Option<CatalogSearchField>,
    language: Option<&str>,
) -> Result<Vec<CatalogSearchHit>, DiscoverError>

Like catalog_search, optionally scoping storefront queries to a facet (author / narrator / series / genre). When language is set it is applied as a hard include filter (unknown/missing language still passes).

Arguments

  • registry - Configured content-source or integration registry.
  • query - Query vector or free-text search string.
  • region - Marketplace / region code (us, uk, …).
  • limit - Maximum number of results to return.
  • field - Optional catalog search field scope.
  • language - Optional preferred language code.

Returns

On success, the inner Vec<CatalogSearchHit> value.

Errors

Returns an error when the underlying I/O, parse, network, or store operation fails.

embed_dirty_works

pub async fn embed_dirty_works(
    library: &LibraryStore,
    embedder: &mut dyn Embedder,
) -> Result<usize, DiscoverError>

Embed works whose text hash changed (or are missing), and drop the embeddings of works that no longer exist.

Walks works in keyset pages of [EMBED_PAGE_WORKS]: each page costs one read of the works, one chunked read of their stored hashes, and one embedder call for the dirty ones, so memory stays bounded by the page and the store sees no per-work lookup.

Arguments

  • library - Open library store used for reads/writes.
  • embedder - Embedding backend that produces dense vectors.

Returns

How many embeddings were written.

Errors

Returns an error when a store read or write fails, or when the embedder fails or returns a different number of vectors than texts.

open_embedder

pub fn open_embedder() -> Box<dyn Embedder>

Opens the embedder the host uses while no plugin serves text embeddings.

Returns

The local-hash embedder, LOCAL_HASH_DIMENSIONS numbers a vector.

text_for_work

pub fn text_for_work(work: &WorkRecord) -> String

Build the text blob embedded for a work.

Arguments

  • work - Library work row whose metadata is turned into embedding text.

Returns

String result for this operation.

candidate_map_key

pub fn candidate_map_key(c: &StorefrontCandidate) -> String

Stable HashMap key for a storefront candidate (hard id, soft title+author, or source:product).

Arguments

  • c - c input for this call.

Returns

String result for this operation.

hard_work_key

pub fn hard_work_key(asin: Option<&str>, isbn: Option<&str>) -> Option<String>

Hard bibliographic key: canonical ISBN first, then ASIN.

Note: ISBN is not published by every storefront (Chirp / GraphicAudio / Audible public search often omit it). Soft title+author matching then applies.

Arguments

  • asin - Optional Audible / Amazon ASIN.
  • isbn - Optional ISBN (any punctuation; normalized internally).

Returns

Some(...) when found / applicable; otherwise None.

identities_match

pub fn identities_match(a: WorkIdentity<'_>, b: WorkIdentity<'_>) -> bool

Whether two bibliographic identities refer to the same work.

Arguments

  • a - Left-hand vector.
  • b - Right-hand vector.

Returns

true when the predicate holds.

merge_candidate_metadata

pub fn merge_candidate_metadata(
    into: &mut StorefrontCandidate,
    from: &StorefrontCandidate,
)

Merge storefront metadata into into, preferring filled fields / richer text.

Arguments

  • into - into input for this call.
  • from - from input for this call.

merge_recommendation

pub fn merge_recommendation(into: &mut Recommendation, from: Recommendation)

Merge a scored recommendation into an existing card.

Arguments

  • into - into input for this call.
  • from - from input for this call.

parse_series_index

pub fn parse_series_index(raw: Option<&str>) -> Option<f64>

Parse Audible/Chirp-style series indexes ("1", "1.5", "Book 2", "02").

Arguments

  • raw - String raw for this call.

Returns

Some(...) when found / applicable; otherwise None.

push_edition

pub fn push_edition(editions: &mut Vec<StoreEdition>, edition: StoreEdition)

Appends a store edition when not already present (dedupes on source+product_id).

Arguments

  • editions - editions input for this call.
  • edition - edition input for this call.

push_shelf_category

pub fn push_shelf_category(categories: &mut Vec<String>, kind: &str)

Append a stable shelf-kind tag (finish_series, author, …) if missing.

Arguments

  • categories - String categories for this call.
  • kind - Plugin kind string.

recommendation_map_key

pub fn recommendation_map_key(r: &Recommendation) -> String

Stable HashMap key for a recommendation card (same rules as work_map_key).

Arguments

  • r - r input for this call.

Returns

String result for this operation.

soft_work_key

pub fn soft_work_key(title: &str, authors: Option<&str>) -> String

Soft key from cleaned title + primary author (exact string match only).

Keeps subtitles so series volumes (Infinity Blade: Awakening vs …: Redemption) do not share a HashMap bucket when hard ids are absent. Soft identities_match still joins edition variants (e.g. A Novel).

Arguments

  • title - Display title.
  • authors - Optional author string (comma-separated).

Returns

String result for this operation.

work_map_key

pub fn work_map_key(
    asin: Option<&str>,
    isbn: Option<&str>,
    title: &str,
    authors: Option<&str>,
    source: Option<&str>,
    product_id: Option<&str>,
) -> String

Best stable map key for a recommendation / candidate.

Arguments

  • asin - Optional Audible / Amazon ASIN.
  • isbn - Optional ISBN (any punctuation; normalized internally).
  • title - Display title.
  • authors - Optional author string (comma-separated).
  • source - Storefront id or filesystem source path, depending on call site.
  • product_id - Storefront-native product id.

Returns

String result for this operation.

works_match

pub fn works_match(
    title_a: &str,
    authors_a: Option<&str>,
    title_b: &str,
    authors_b: Option<&str>,
) -> bool

Whether two titles should be treated as the same work.

Arguments

  • title_a - String title_a for this call.
  • authors_a - String authors_a for this call.
  • title_b - String title_b for this call.
  • authors_b - String authors_b for this call.

Returns

true when the predicate holds.

enrich_books_from_metadata

pub async fn enrich_books_from_metadata(
    library: &LibraryStore,
    providers: &dyn MetadataProviders,
    opts: &MetadataEnrichOptions,
) -> Result<usize, DiscoverError>

Fills missing description, subjects, cover and language from the deployed metadata providers.

Walks the held editions and skips those a provider already filled. With no provider deployed, every answer is empty and nothing changes.

Arguments

  • library - Library store read and written.
  • providers - Deployed metadata providers.
  • opts - Pacing for this run.

Returns

The number of editions filled.

Errors

Returns an error when a library read or write fails.

fetch_subject_candidates

pub async fn fetch_subject_candidates(
    library: &LibraryStore,
    registry: &SourceRegistry,
    subject: &DiscoverSubject,
    opts: &RecommendOptions,
) -> Result<FetchReport, DiscoverError>

Fetches one subject's storefront candidates and stores them store by store.

Every deployed storefront is asked, whether or not the subject has an account there. Stores run concurrently; within a store each seed's call has STORE_CALL_TIMEOUT, each store stops starting calls after STORE_FETCH_DEADLINE, and the store's share of opts.storefront_max_remote_calls bounds how many calls it makes. A store's rows replace its previous rows only when it finishes, so a store that fails keeps what it returned last time.

Arguments

  • library - Library store (taste, cache, candidate rows).
  • registry - The deployed storefronts.
  • subject - Whose candidates to fetch.
  • opts - Seed limit, call budget, region and series-set filter.

Errors

Returns a library error from loading the taste. Store failures are reported in FetchReport::stores_failed, not as errors.

load_subject_taste

pub async fn load_subject_taste(
    library: &LibraryStore,
    subject: &DiscoverSubject,
    opts: &RecommendOptions,
) -> Result<SubjectTaste, DiscoverError>

Loads one subject's taste.

A user or portal identity uses the books held by store accounts linked to them, the household books they have listened to, and the works they finished, rated or tagged (a local user with no portal identity has only these), the listening rows recorded for them (by identity id, or by provider and external user id on rows recorded before the identity was known), and their open wishlist. While they have fewer than OWN_TASTE_THRESHOLD books and listens of their own, the rest of the household's books blend in at HOUSEHOLD_BLEND_WEIGHT, so a first wish or book adds to the shelves they already had instead of replacing them. With no signal of their own at all (a new member, or a visitor who has connected no store yet), and always for the operator, the household library is used as it stands.

Arguments

  • library - Library store.
  • subject - Whose taste to load.
  • opts - include_listening and listening_providers apply as on the page.

Errors

Returns the library read error.

rank_subject_feed

pub async fn rank_subject_feed(
    library: &LibraryStore,
    registry: &SourceRegistry,
    subject: &DiscoverSubject,
    opts: &RecommendOptions,
) -> Result<RankReport, DiscoverError>

Ranks one subject's stored candidates into shelves and stores the feed.

No storefront is called (include_purchase_hints is ignored: cards fetch live prices when they scroll into view). Owned titles are filtered again, so a title bought since the fetch drops out.

Arguments

  • library - Library store.
  • registry - Unused for network; passed through to ranking.
  • subject - Whose feed to rank.
  • opts - Ranking options; disabled_shelves is ignored (applied on read).

Errors

Returns the library read or write error.

refresh_subject_taste

pub async fn refresh_subject_taste(
    library: &LibraryStore,
    subject: &DiscoverSubject,
    opts: &RecommendOptions,
) -> Result<(), DiscoverError>

Loads subject's taste from the library and stores it, so the next ranking reads it: what a candidate fetch does first, for a fetch that calls no storefront (storefront_candidates = false), whose taste events must still refresh the ranking.

Errors

Returns the library read or write error.

stored_subject_feed

pub async fn stored_subject_feed(
    library: &LibraryStore,
    subject: &DiscoverSubject,
    disabled_shelves: &[String],
) -> Result<Option<StoredSubjectFeed>, DiscoverError>

Reads one subject's stored feed, drops their hidden shelves and joins each card's catalog metadata from the candidate pool.

The stored feed keeps card references and what is personal to the subject; the description, cover and other metadata of the subject's listings are read from the pool here, in chunks that stay under the database plugin's result limit.

Returns

None when the subject has no stored feed yet, or it does not decode (written by another release); the caller then shows placeholders and queues a ranking.

Errors

Returns the library read error.

stored_subject_feed_state

pub async fn stored_subject_feed_state(
    library: &LibraryStore,
    subject: &DiscoverSubject,
) -> Result<Option<StoredSubjectFeed>, DiscoverError>

Reads one subject's stored feed without joining its catalog metadata, for callers that need only whether it exists and when it was ranked.

The cards come back as stored: references and the subject's own fields, without the description, cover and other metadata stored_subject_feed joins from the candidate pool. Hidden shelves are kept. No candidate row is read.

Returns

None when the subject has no stored feed yet, or it does not decode.

Errors

Returns the library read error.

best_purchase_hint

pub fn best_purchase_hint(hints: &[PurchaseHint]) -> Option<&PurchaseHint>

Pick the lowest-priced hint (ties keep earlier order). Unpriced sort after priced.

Arguments

  • hints - Purchase hints to pick from.

Returns

Some(...) when found / applicable; otherwise None.

best_purchase_hint_preferring

pub fn best_purchase_hint_preferring<'a>(
    hints: &'a [PurchaseHint],
    preferred: &HashSet<String>,
) -> Option<&'a PurchaseHint>

Pick the offer the caller would actually pay least for.

Linked storefronts (preferred) are compared at member price; every other store is compared at list / non-member price. That way a Libro-only member still sees Audible on the shelf when Audible’s non-member price beats Libro’s member price. When nothing is linked, all stores are compared as non-members. Hints with no usable price for that role sort last.

Arguments

  • hints - Purchase hints to pick from.
  • preferred - String preferred for this call.

Returns

Some(...) when found / applicable; otherwise None.

format_money_label

pub fn format_money_label(cents: i64, currency: &str) -> String

Formats integer cents into a storefront-style money label for currency.

Arguments

  • cents - Integer cents to format.
  • currency - ISO 4217 currency code.

Returns

String result for this operation.

parse_money_label_to_cents

pub fn parse_money_label_to_cents(raw: &str) -> Option<i64>

Parse $12.34 / 12.34 / FREE into cents.

Arguments

  • raw - String raw for this call.

Returns

Some(...) when found / applicable; otherwise None.

purchase_hints_for

pub async fn purchase_hints_for(
    registry: &SourceRegistry,
    title: &str,
    author: Option<&str>,
    asin: Option<&str>,
    isbn: Option<&str>,
    region: &str,
) -> Result<Vec<PurchaseHint>, DiscoverError>

Look up purchase links via registered bookclerk_source::ContentSource::purchase_hint (no prices).

Call resolve_purchase_hints for multi-store + live pricing.

Arguments

  • registry - Configured content-source or integration registry.
  • title - Display title.
  • author - String author for this call.
  • asin - Optional Audible / Amazon ASIN.
  • isbn - Optional ISBN (any punctuation; normalized internally).
  • region - Marketplace / region code (us, uk, …).

Returns

On success, the inner Vec<PurchaseHint> value.

Errors

Returns an error when the underlying I/O, parse, network, or store operation fails.

resolve_purchase_hints

pub async fn resolve_purchase_hints(
    registry: &SourceRegistry,
    library: Option<&LibraryStore>,
    query: &PurchaseHintsQuery,
) -> Result<PurchaseHintsResponse, DiscoverError>

Resolve every catalog match and attach live prices (view-time).

One query through resolve_purchase_hints_batch, so a single card is priced the same way as a page of them: the same lookups, the same evaluation of title-search records, and the same cache.

Arguments

  • registry - Configured content-source or integration registry.
  • library - The library whose listing pool places title-search records; None keeps only records that carry the card's ISBN or ASIN.
  • query - The card to price.

Returns

On success, the inner PurchaseHintsResponse value.

Errors

Returns an error when the underlying I/O, parse, network, or store operation fails.

resolve_purchase_hints_batch

pub async fn resolve_purchase_hints_batch(
    registry: &SourceRegistry,
    library: Option<&LibraryStore>,
    queries: &[PurchaseHintsQuery],
    max_concurrent: usize,
) -> Vec<Result<PurchaseHintsResponse, DiscoverError>>

Resolve many purchase-hint queries at once (order preserved).

Queries answered from the cache are done at once. For the rest, every store is asked once, through bookclerk_source::ContentSource::purchase_hints, for all of them together, so a store whose catalog prices many products per request makes one request for a page of cards. The whole batch answers within [BATCH_DEADLINE]: a store still working then counts as timed out. A query no store answered with a hint (timed out, paused, or never tried within a guest's own budget) carries its trusted seeds alone (no prices) and incomplete set: it is not cached, so the page shows a link rather than nothing, keeps no copy, and asks again later. A store that asks to slow down (bookclerk_source::SourceError::RateLimited) is left alone for the time it said (see RATE_LIMIT_FIRST_PAUSE).

Each store is asked the strongest way it supports: by the product it already sells, by the card's exact ISBN or ASIN when it declared that lookup, else by title. A title search's records are stored in the listing pool and kept only for the card's recording.

Arguments

  • registry - Configured content-source or integration registry.
  • library - The library whose listing pool places title-search records, keeping those of the card's recording; None keeps only records that carry the card's ISBN or ASIN.
  • queries - Batch of purchase-hint queries.
  • max_concurrent - Unused since each store is asked once; kept for the route's call shape.

Returns

One result per query, in request order.

retain_card_recording

pub async fn retain_card_recording(
    library: &LibraryStore,
    registry: &SourceRegistry,
    query: &PurchaseHintsQuery,
    response: &mut PurchaseHintsResponse,
) -> Result<(), DiscoverError>

Drops live purchase hints that sell another recording than the card's.

A store answers a price lookup by searching its catalog, and the host can only check the answer's title, so a store whose first hit is another recording of the book (a full-cast dramatisation for a narration) would price the card with it. The shared listing pool knows which expression (recording) each listed product is: when it knows the card's own editions, a hint whose product the pool placed only in other expressions is dropped, and best is picked again. A hint for a product the pool never listed stays, as does every hint when the pool knows none of the card's editions.

Arguments

  • library - The library whose listing pool is read.
  • registry - Storefronts, to name each hint's store by its PluginKey.
  • query - The card's lookup: its candidate edition and store editions.
  • response - The resolved hints, filtered in place.

Errors

Returns the library read error.

retain_card_recordings

pub async fn retain_card_recordings(
    library: &LibraryStore,
    registry: &SourceRegistry,
    queries: &[PurchaseHintsQuery],
    responses: &mut [PurchaseHintsResponse],
) -> Result<(), DiscoverError>

retain_card_recording for a batch of cards, with one pool read.

A batch route checks every card's hints at once: the pool is read once for all the cards' editions and hints together, instead of once per card one after another.

Arguments

  • library - The library whose listing pool is read.
  • registry - Storefronts, to name each hint's store by its PluginKey.
  • queries - The cards' lookups, in batch order.
  • responses - Their resolved hints, in the same order, filtered in place; a response without a query (or a query without a response) is left alone.

Errors

Returns the library read error; no response is changed then.

seed_purchase_hint

pub fn seed_purchase_hint(
    source: &str,
    product_id: &str,
    title: Option<String>,
    region: &str,
) -> Option<PurchaseHint>

Seed a deterministic storefront URL from a known candidate (no remote I/O).

Arguments

  • source - Storefront id or filesystem source path, depending on call site.
  • product_id - Storefront-native product id.
  • title - Display title.
  • region - Marketplace / region code (us, uk, …).

Returns

Some(...) when found / applicable; otherwise None.

combine_wishlist_score

pub fn combine_wishlist_score(taste_score: f64, wish_count: i64) -> f64

Combine local recommend taste with a heavy multi-user wishlist boost.

Arguments

  • taste_score - taste_score input for this call.
  • wish_count - Numeric wish_count value for this call.

Returns

f64 result.

listening_engagement

pub fn listening_engagement(row: &ListeningSignal) -> f64

Continuous engagement from a listening progress row (≈0.0–6.0).

Absolute hours heard are the primary signal — 50% of a 30‑hour title (15 h) outweighs 50% of a 3‑hour title (1.5 h). Percent complete is only a secondary completion bonus, not the main weight.

Arguments

  • row - SeaORM query row to project into an RPC DTO.

Returns

f64 result.

rank_request_queue_taste

pub async fn rank_request_queue_taste(
    library: &LibraryStore,
    opts: &RecommendOptions,
) -> Result<Vec<QueueRank>, DiscoverError>

Ranks every entry of the shared request queue against household taste, for the discover_request_queue job to store.

This ranking is not personalized: portal external_user_id filters are ignored so every viewer sees the same shared queue order (the household library and all listening progress). Every wish names its work, so one ranking per work matches the entry the read builds.

Only taste is ranked here: the wish-count boost and the wish reasons are added when the queue is read, from the live counts, so a new wish moves an entry before the next pass. Entries the library already holds are kept with owned set, so the read can hide them.

Arguments

  • library - Open library store.
  • opts - Ranking options (embedder, listening filters).

Returns

One ranking per merged queue entry (empty when the queue is).

Errors

Returns the library read error, or the embedder's open error.

recommend

pub async fn recommend(
    library: &LibraryStore,
    registry: &SourceRegistry,
    opts: &RecommendOptions,
) -> Result<Vec<Recommendation>, DiscoverError>

Build ranked recommendations for the operator (or a specific external user).

Arguments

  • library - Open library store used for reads/writes.
  • registry - Configured content-source or integration registry.
  • opts - Options struct for this operation.

Returns

On success, the inner Vec<Recommendation> value.

Errors

Returns an error when the underlying I/O, parse, network, or store operation fails.

recommend_feed

pub async fn recommend_feed(
    library: &LibraryStore,
    registry: &SourceRegistry,
    opts: &RecommendOptions,
) -> Result<DiscoverFeed, DiscoverError>

Personalized Discover feed (Netflix-style shelves) from the same candidate pool.

Arguments

  • library - Open library store used for reads/writes.
  • registry - Configured content-source or integration registry.
  • opts - Options struct for this operation.

Returns

On success, the inner crate::shelves::DiscoverFeed value.

Errors

Returns an error when the underlying I/O, parse, network, or store operation fails.

read_request_queue

pub async fn read_request_queue(
    library: &LibraryStore,
) -> Result<StoredRequestQueue, DiscoverError>

Builds the ranked queue from the open requests and the stored ranking.

An entry with no stored ranking yet (wished since the last pass) is shown with no taste score, so wish count alone places it until the next pass; an entry the last pass found in the library is hidden.

Arguments

  • library - Open library store.

Errors

Returns the library read error.

build_discover_feed

pub fn build_discover_feed(
    recs: &[Recommendation],
    taste: &ShelfTaste,
    per_shelf: usize,
    disabled_shelves: &[String],
) -> DiscoverFeed

Partitions scored recommendations into Discover shelves.

Every title lands on one shelf. Shelves claim titles in the order they are built: the wishlist first, then the series shelves, the subject's wishes, authors, narrators, genres, starter genres, similar taste, Chirp deals, then one shelf per store for whatever is left, each title under the store where it costs the subject least (member price on stores they have an account with, list price elsewhere, its own store when no price is known). A wished title shows on the wishlist shelf alone. Shelves other than the series shelves and the wishlist keep at most SERIES_CAP titles of one series; those rotate between series instead.

Arguments

  • recs - Scored recommendations to partition into shelves.
  • taste - Local taste context used to title personalized shelves.
  • per_shelf - Max items per shelf (clamped).
  • disabled_shelves - Shelf kind ids the operator has ignored.

Returns

DiscoverFeed result.

flatten_feed

pub fn flatten_feed(feed: &DiscoverFeed, limit: usize) -> Vec<Recommendation>

Flatten shelves into a unique score-sorted list (CLI / legacy).

Arguments

  • feed - Discover feed to flatten.
  • limit - Maximum number of results to return.

Returns

Collected results (may be empty).

shelf_is_disabled

pub fn shelf_is_disabled(shelf_id: &str, disabled: &[String]) -> bool

Whether shelf_id matches an ignore entry (exact, kind prefix, or from_store).

Arguments

  • shelf_id - Shelf id to test against the ignore list.
  • disabled - Ignore-list entries from user preferences.

Returns

true when the predicate holds.

shelf_kind_catalog

pub fn shelf_kind_catalog() -> Vec<ShelfKindInfo>

Shelf kinds Discover can emit (for config / UI ignore lists).

check_title_meta_query

pub fn check_title_meta_query(query: &TitleMetaQuery) -> Result<(), TitleMetaQueryProblem>

Checks a title-meta query from a client before it is resolved.

Errors

Returns TitleMetaQueryProblem::TooManyStoreEditions when the query names more than TITLE_META_MAX_STORE_EDITIONS editions, and TitleMetaQueryProblem::NothingToLookUp when its title, ASIN and ISBN are all blank.

plan_title_meta_fill

pub fn plan_title_meta_fill<S>(
    query: &TitleMetaQuery,
    resolve: impl Fn(&str) -> Option<S>,
    isbn_stores: impl IntoIterator<Item = S>,
    lookups: impl Fn(&S) -> FillStoreLookups,
) -> Vec<(S, FillLookup)>

Plans the catalog-detail lookups that can fill query, in the order to try them.

Each listing store that declared detailByProductId comes first, by its own product id (in the query's edition order, at most two), then each store in isbn_stores that declared detailByIsbn, by the title's ISBN (or an ISBN-shaped ASIN). A store already asked for the same id is skipped, and the plan holds at most three lookups. Reads only declared capabilities, so no guest is woken to plan.

Arguments

  • query - The title-meta query, already checked.
  • resolve - Finds the store an edition names by its source id.
  • isbn_stores - The stores that may be asked by ISBN, in order.
  • lookups - What a store declared.

Returns

The stores to ask, each with the lookup to make.

resolve_title_meta

pub async fn resolve_title_meta(
    query: &TitleMetaQuery,
    providers: Arc<dyn MetadataProviders>,
    sources: Option<&SourceRegistry>,
) -> Result<Option<TitleMeta>, DiscoverError>

Resolve public metadata for a title detail dialog.

When sources is provided, sparse Audible/Audnexus results are gap-filled from storefront [bookclerk_source::ContentSource::catalog_detail]: the listing stores that declared detailByProductId, then the stores that declared detailByIsbn.

Arguments

  • query - Query vector or free-text search string.
  • providers - Deployed metadata providers asked for records.
  • sources - String sources for this call.

Returns

On success, the inner Option<TitleMeta> value.

Errors

Returns an error when the underlying I/O, parse, network, or store operation fails.

resolve_title_meta_batch

pub async fn resolve_title_meta_batch(
    queries: &[TitleMetaQuery],
    max_concurrent: usize,
    providers: Arc<dyn MetadataProviders>,
    sources: Option<&SourceRegistry>,
) -> Vec<Result<Option<TitleMeta>, DiscoverError>>

Resolve many title-meta queries with bounded concurrency (order preserved).

At most max_concurrent queries run at once, and each finished query frees its slot for the next one at once (no query waits for the slowest of a group). The batch answers within TITLE_META_BATCH_DEADLINE.

Arguments

  • queries - Batch of title-meta queries.
  • max_concurrent - Most queries resolving at once (clamped to 1..=8).
  • providers - Deployed metadata providers asked for records.
  • sources - The deployed storefronts, for gap-filling from their catalogs.

Returns

One result per query, in order. A query that failed, was cancelled or did not finish by the deadline is an error.

resolve_title_reviews

pub async fn resolve_title_reviews(
    query: &TitleReviewsQuery,
) -> Result<TitleReviewsPage, DiscoverError>

Resolve one page of Audible customer reviews for infinite scroll.

Arguments

  • query - Query vector or free-text search string.

Returns

On success, the inner TitleReviewsPage value.

Errors

Returns an error when the underlying I/O, parse, network, or store operation fails.

pool_wish_editions

pub async fn pool_wish_editions(
    library: &LibraryStore,
    registry: &SourceRegistry,
    editions: &[(String, String)],
    hints: &[PurchaseHint],
    region: &str,
) -> Vec<PooledEdition>

Asks each store about the editions a wish names and records the answers in the shared pool.

Editions are looked up concurrently, each within EDITION_LOOKUP_TIMEOUT. An edition whose store is not deployed, does not answer in time, fails or does not know the product is left out: the wish is still saved, with that edition's row naming no listing. Server side purchase hints for the same editions add the member price they quote to the pooled listing, since they also come from the store.

Arguments

  • library - The library whose pool records the listings.
  • registry - The deployed storefronts.
  • editions - (source, product_id) pairs, in the wish's order; blank and repeated pairs are skipped, and at most MAX_WISH_EDITIONS are asked about.
  • hints - Purchase hints the server resolved for the wish.
  • region - The marketplace the stores are asked about.

Returns

One entry per edition the pool now holds, in the order given.

record_wish_member_offers

pub async fn record_wish_member_offers(
    library: &LibraryStore,
    pooled: &[PooledEdition],
    hints: &[PurchaseHint],
)

Stores the member prices hints quote for editions already pooled.

pool_wish_editions records these itself when it is given the hints; a wish that looks its named editions up at the same time as the prices calls this once both are in.

Arguments

  • library - The library whose pool holds the listings.
  • pooled - The pooled editions, as pool_wish_editions returned them.
  • hints - The purchase hints the server resolved for the wish.

Constants

EMBED_PAGE_WORKS

pub const EMBED_PAGE_WORKS: u64 = 128;

Works read per page by embed_dirty_works; also the most texts one embedder call receives.

LOCAL_HASH_DIMENSIONS

pub const LOCAL_HASH_DIMENSIONS: usize = 384;

Numbers in one hash vector.

MODEL_LOCAL_HASH_V1

pub const MODEL_LOCAL_HASH_V1: &str = "local-hash-v1";

Model id stored beside hash vectors. They are never compared with a model's vectors.

DEFAULT_MAX_REQUESTS_PER_RUN

pub const DEFAULT_MAX_REQUESTS_PER_RUN: usize = 25;

Default cap on provider asks in one run.

METADATA_ENRICH_SOURCE_PREFIX

pub const METADATA_ENRICH_SOURCE_PREFIX: &str = "metadata:";

enrich_source prefix marking a title filled by a metadata provider; the provider's plugin key follows it.

HOUSEHOLD_BLEND_WEIGHT

pub const HOUSEHOLD_BLEND_WEIGHT: f64 = 0.5;

How much a household book counts in a member's taste while it blends in, relative to one of their own.

OWN_TASTE_THRESHOLD

pub const OWN_TASTE_THRESHOLD: usize = 5;

Books and listens of their own a subject needs before the household's books stop blending into their taste.

STARTER_GENRES

pub const STARTER_GENRES: [&str; 6] = _;

Genres browsed for a thin taste, in the order the stores are asked (the call budget may stop before the end).

STARTER_GENRE_MIN_SEEDS

pub const STARTER_GENRE_MIN_SEEDS: usize = 5;

Seeds below which a fetch also browses each store's STARTER_GENRES, so a new library still gets shelves.

STORE_CALL_MAX_AGE

pub const STORE_CALL_MAX_AGE: Duration = _;

How long a cached storefront answer is reused (the daily refresh).

STORE_CALL_TIMEOUT

pub const STORE_CALL_TIMEOUT: Duration = _;

Longest one storefront call may take before its store moves on.

STORE_FETCH_DEADLINE

pub const STORE_FETCH_DEADLINE: Duration = _;

How long one store may keep starting new calls in a fetch.

A store that is slow on every call stops asking once this has passed and saves what it has, so it delays the subject's ranking by at most this plus one STORE_CALL_TIMEOUT.

BATCH_DEADLINE

pub const BATCH_DEADLINE: Duration = _;

Longest a batch waits for its lookups before answering with what has resolved. Under the daemon's 25 s route budget, so a slow store never turns a page of cards into one failed request.

BREAKER_OPEN_FOR

pub const BREAKER_OPEN_FOR: Duration = _;

How long a tripped store is skipped. After that, lookups ask it again, and BREAKER_TRIP_TIMEOUTS more timeouts in a row pause it again.

BREAKER_TRIP_TIMEOUTS

pub const BREAKER_TRIP_TIMEOUTS: u32 = 3;

Timeouts in a row after which a store's price lookups are skipped.

RATE_LIMIT_FIRST_PAUSE

pub const RATE_LIMIT_FIRST_PAUSE: Duration = _;

How long a store that asked to slow down without saying for how long is left alone the first time; each repeat doubles it.

RATE_LIMIT_MAX_PAUSE

pub const RATE_LIMIT_MAX_PAUSE: Duration = _;

Longest pause a rate limit can grow to by doubling, and the most a store's own Retry-After is honored for.

WISH_COUNT_WEIGHT

pub const WISH_COUNT_WEIGHT: f64 = 40.0;

Per open wish on the global queue. Large enough that multi-user demand dominates typical local taste scores (~1–25) while recommend signals still order titles that share the same wish count.

REQUEST_QUEUE_MAX_AGE

pub const REQUEST_QUEUE_MAX_AGE: Duration = _;

How old the stored ranking may get before a read asks for a new pass, so taste changes no event announces (a book removed, a rating edited) still reach the queue within a day.

SERIES_CAP

pub const SERIES_CAP: usize = 2;

Most titles of one series on a shelf that is not about series, so one long series cannot crowd the others out.

TITLE_META_BATCH_DEADLINE

pub const TITLE_META_BATCH_DEADLINE: Duration = _;

Longest a title-meta batch waits before answering with what resolved.

A query still working then answers as failed (the route shows no metadata for it, and the browser asks again later), and keeps running in the background so its answer is cached for that next ask.

TITLE_META_MAX_STORE_EDITIONS

pub const TITLE_META_MAX_STORE_EDITIONS: usize = 16;

Most store editions one title-meta query may name; the API rejects more (keep TitleMetaQuery::store_editions's doc in step).

MAX_WISH_EDITIONS

pub const MAX_WISH_EDITIONS: usize = 8;

Most store editions looked up for one wish. A wish names a few; the cap bounds what a crafted request can make the server fetch.

Generated from crates/bookclerk-discover at main · View as Markdown