bookclerk_resolve::listing
The validated listing a storefront reports, and who holds it.
ListingDraft is what a plugin said, unchecked. Listing::from_draft
is the boundary: it trims and normalises every field, drops blank
identifiers, credits and series, removes duplicates, and refuses records
that are empty or too large. The resolver only ever sees a Listing.
| Item | Kind | Summary |
|---|---|---|
ListingKey |
struct | What a store sells, keyed the way store_listings is. |
Credit |
struct | One credited contributor on a listing, with its resolved level. |
SeriesEntry |
struct | A work's place in one series, as a listing reports it. |
ListingDraft |
struct | An unchecked listing, field for field as a plugin reported it. |
Listing |
struct | A validated, normalised listing: the resolver's only input record. |
HoldingDraft |
struct | Ownership details a scan reports with a listing. |
Holder |
enum | Who owns a listing (holdings.holder). |
ListingError |
enum | Why a draft listing was refused. |
stored_marketplace |
function | The stored spelling of a marketplace a source reported: trimmed, lower-cased, and DEFAULT_MARKETPLACE when blank. |
stored_product_id |
function | The stored spelling of a product id a source reported: its words joined by single spaces, as a listing keeps it, so a title row holding the raw value still finds its listing. |
work_match_key |
function | The work matcher's key for a title and its authors. |
canonical_language |
function | The one spelling the resolver stores and compares for a language. |
DEFAULT_MARKETPLACE |
constant | The marketplace a listing that names none is sold in. |
MAX_TEXT_BYTES |
constant | Longest text field accepted, in bytes. |
MAX_IDENTIFIERS |
constant | Most identifiers one listing may carry; keeps one listing's link batch within every database engine's statement cap. |
MAX_CREDITS |
constant | Most credits one listing may carry. |
MAX_SERIES |
constant | Most series entries one listing may carry; small enough that a work's series and series entries are written in one credit batch, so they are never left part-written. |
pub struct ListingKey {
pub plugin_key: String,
pub marketplace: String,
pub product_id: String,
}
What a store sells, keyed the way store_listings is.
Fields
plugin_key: Provenance-qualified PluginKey of the storefront.marketplace: Lower-cased marketplace (us,uk, …).product_id: The store's own product id.
Implements: Clone, Debug, Eq, Hash, Ord, PartialEq, PartialOrd
pub struct Credit {
pub name: String,
pub role: CreditRole,
pub level: Level,
}
One credited contributor on a listing, with its resolved level.
Fields
name: Display name, whitespace collapsed.role: What the contributor did.level: The level the credit attaches to.
pub fn name_key(&self) -> String
The cleaned name contributors are matched by.
Implements: Clone, Debug, Eq, Hash, Ord, PartialEq, PartialOrd
pub struct SeriesEntry {
pub name: String,
pub position: Option<String>,
}
A work's place in one series, as a listing reports it.
Fields
name: Series name, whitespace collapsed.position: Position label (1,2.5,1-3) when known.
pub fn name_key(&self) -> String
The cleaned name series are matched by (see crate::series_key),
so King & Maxwell and King and Maxwell are one series.
pub fn sort_position(&self) -> Option<f64>
The position as a sortable number: the leading decimal of the label.
1-3 sorts as 1 and Book 2 as 2; a label without digits has none.
Implements: Clone, Debug, Eq, Hash, Ord, PartialEq, PartialOrd
pub struct ListingDraft {
pub plugin_key: String,
pub marketplace: Option<String>,
pub product_id: String,
pub work_kind: Option<WorkKind>,
pub expression_kind: Option<ExpressionKind>,
pub media_kind: Option<MediaKind>,
pub language: Option<String>,
pub abridgement: Option<Abridgement>,
pub title: String,
pub subtitle: Option<String>,
pub published_at: Option<String>,
pub duration_minutes: Option<i64>,
pub categories: Option<String>,
pub identifiers: Vec<(IdentifierScheme, String, Option<String>)>,
pub credits: Vec<(String, CreditRole, Option<Level>)>,
pub series: Vec<(String, Option<String>)>,
pub parent_product_id: Option<String>,
}
An unchecked listing, field for field as a plugin reported it.
Fields
plugin_key: PluginKey of the storefront; the host sets it, never the guest.marketplace: Marketplace when known; blank reads asus.product_id: The store's own product id.work_kind: Kind of work.expression_kind: How the work is realised.media_kind: Carrier of the edition.language: Content language code when known.abridgement: Abridgement as reported.title: Title.subtitle: Subtitle when distinct from the title.published_at: Publication date (RFC 3339) when known.duration_minutes: Runtime in whole minutes when known.categories: Category labels as one string when known.identifiers: Identifiers: scheme, raw value, and the marketplace the source gave.credits: Credits in billing order: name, role, and a level when the source departs from the role's usual one.series: Series entries: name and position label.parent_product_id: Parent show's product id, for a podcast episode (a podcast that names its show).
Implements: Clone, Debug, Default, PartialEq
pub struct Listing {
pub key: ListingKey,
pub work_kind: WorkKind,
pub expression_kind: ExpressionKind,
pub media_kind: MediaKind,
pub language: Option<String>,
pub abridgement: Abridgement,
pub title: String,
pub subtitle: Option<String>,
pub published_at: Option<String>,
pub duration_minutes: Option<i64>,
pub categories: Option<String>,
pub identifiers: Vec<IdentifierKey>,
pub credits: Vec<Credit>,
pub series: Vec<SeriesEntry>,
pub parent_product_id: Option<String>,
}
A validated, normalised listing: the resolver's only input record.
Fields
key: The store, marketplace and product it is.work_kind: Kind of work.expression_kind: How the work is realised.media_kind: Carrier of the edition.language: Language code in one spelling per language (seecanonical_language);Nonewhen unknown.abridgement: Abridgement;Abridgement::Unknownwhen the source did not say.title: Title, whitespace collapsed.subtitle: Subtitle, whitespace collapsed.published_at: Publication date (RFC 3339) when known.duration_minutes: Runtime in whole minutes when known.categories: Category labels when known.identifiers: Normalised identifiers, duplicates removed, in reported order.credits: Credits in billing order, duplicates removed.series: Series entries, duplicates removed.parent_product_id: The parent show's product id, for a podcast episode only.
pub fn from_draft(draft: &ListingDraft) -> Result<Self, ListingError>
Validates and normalises a draft.
draft- The listing as the plugin reported it.
The normalised listing. A podcast keeps its parent id (an episode names its show); a book drops it.
Returns ListingError when a kind is absent, the plugin key,
product id or title is blank, a text field is too long, or a list is
over its limit.
pub fn is_episode(&self) -> bool
Whether this listing is a podcast episode: a podcast that names its show. A podcast without a parent is the show.
pub fn parent_key(&self) -> Option<ListingKey>
The listing of this one's parent show, for an episode with a parent id.
pub fn credits_at(&self, level: Level) -> impl Iterator<Item = &Credit>
Credits attached at level, in billing order.
pub fn edition_identifiers(&self) -> impl Iterator<Item = &IdentifierKey>
Identifiers whose scheme names an edition, in reported order.
pub fn work_identifiers(&self) -> impl Iterator<Item = &IdentifierKey>
Identifiers whose scheme names a work, in reported order.
pub fn work_match_key(&self) -> String
The work matcher's key: cleaned title and sorted author names.
Empty when the cleaned title is empty or no author is credited at the work level, so such a listing is never matched by text alone.
pub fn expression_credit_key(&self) -> String
The expression's credit key: its credits as sorted, cleaned
role:name pairs, so two realisations whose people swap roles
(narrator and translator, say) never compare equal.
Implements: Clone, Debug, PartialEq
pub struct HoldingDraft {
pub holder: Holder,
pub entitlement: Entitlement,
pub purchased_at: Option<String>,
}
Ownership details a scan reports with a listing.
Fields
holder: Who holds the listing.entitlement: How they hold it.purchased_at: When they bought or added it (RFC 3339), when known.
Implements: Clone, Debug, Eq, PartialEq
pub enum Holder {
Account(String),
Node(String),
Patron(i64),
}
Who owns a listing (holdings.holder).
Variants
Account: A store account of the listing's plugin, by account id.Node: A branch library, by node id (node:<node_id>provenance).Patron: A patron who uploaded the book, by user id (patron:<user id>).
pub fn stored(&self) -> String
The stored text: account:<id>, node:<id> or patron:<user id>.
pub fn parse(text: &str) -> Option<Self>
Parses stored holder text; None for any other shape.
Implements: Clone, Debug, Eq, Hash, Ord, PartialEq, PartialOrd
pub enum ListingError {
Blank(&'static str),
TooLong(&'static str),
TooMany(&'static str),
NegativeDuration,
MissingKind(&'static str),
}
Why a draft listing was refused.
Variants
Blank: A required field (plugin key, product id or title) is blank.TooLong: A text field is longer thanMAX_TEXT_BYTES.TooMany: A list holds more entries than its limit.NegativeDuration: The runtime is negative.MissingKind: A kind (work, expression or media) is absent: every record names all three, so a plugin that leaves one unspecified is refused.
Implements: Clone, Debug, Display, Eq, Error, PartialEq
pub fn stored_marketplace(raw: &str) -> String
The stored spelling of a marketplace a source reported: trimmed,
lower-cased, and DEFAULT_MARKETPLACE when blank.
pub fn stored_product_id(raw: &str) -> String
The stored spelling of a product id a source reported: its words joined by single spaces, as a listing keeps it, so a title row holding the raw value still finds its listing.
pub fn work_match_key<'a>(title: &str, authors: impl Iterator<Item = &'a str>) -> String
The work matcher's key for a title and its authors.
title- Work title (decoded, any case).authors- Author display names.
The clean_title of the title without its trailing edition markers
(see [crate::strip_edition_marker]: First Family - Abridged keys as
First Family) and the sorted, de-duplicated clean_author names
joined with unit separators; empty when either side is empty.
pub fn canonical_language(raw: &str) -> String
The one spelling the resolver stores and compares for a language.
A language crate::normalize_language recognises becomes its short
code (English, eng and en-US are all en), so the same recording
sold by two stores lands in one expression. Anything else is kept,
lower-cased, rather than dropped: an unrecognised language still only
matches itself.
raw- The language as a store or a stored row spells it.
The canonical code.
pub const DEFAULT_MARKETPLACE: &str = "us";
The marketplace a listing that names none is sold in.
pub const MAX_TEXT_BYTES: usize = 4096;
Longest text field accepted, in bytes.
pub const MAX_IDENTIFIERS: usize = 12;
Most identifiers one listing may carry; keeps one listing's link batch within every database engine's statement cap.
pub const MAX_CREDITS: usize = 128;
Most credits one listing may carry.
pub const MAX_SERIES: usize = 12;
Most series entries one listing may carry; small enough that a work's series and series entries are written in one credit batch, so they are never left part-written.
Generated from crates/bookclerk-resolve at main · View as Markdown