bookclerk_resolve::listing

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

Last updated View as Markdown

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.

Structs

ListingKey

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

Credit

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.

Credit::name_key

pub fn name_key(&self) -> String

The cleaned name contributors are matched by.

Implements: Clone, Debug, Eq, Hash, Ord, PartialEq, PartialOrd

SeriesEntry

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.

SeriesEntry::name_key

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.

SeriesEntry::sort_position

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

ListingDraft

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 as us.
  • 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

Listing

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 (see canonical_language); None when unknown.
  • abridgement: Abridgement; Abridgement::Unknown when 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.

Listing::from_draft

pub fn from_draft(draft: &ListingDraft) -> Result<Self, ListingError>

Validates and normalises a draft.

Arguments
  • draft - The listing as the plugin reported it.
Returns

The normalised listing. A podcast keeps its parent id (an episode names its show); a book drops it.

Errors

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.

Listing::is_episode

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.

Listing::parent_key

pub fn parent_key(&self) -> Option<ListingKey>

The listing of this one's parent show, for an episode with a parent id.

Listing::credits_at

pub fn credits_at(&self, level: Level) -> impl Iterator<Item = &Credit>

Credits attached at level, in billing order.

Listing::edition_identifiers

pub fn edition_identifiers(&self) -> impl Iterator<Item = &IdentifierKey>

Identifiers whose scheme names an edition, in reported order.

Listing::work_identifiers

pub fn work_identifiers(&self) -> impl Iterator<Item = &IdentifierKey>

Identifiers whose scheme names a work, in reported order.

Listing::work_match_key

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.

Listing::expression_credit_key

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

HoldingDraft

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

Enums

Holder

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>).

Holder::stored

pub fn stored(&self) -> String

The stored text: account:<id>, node:<id> or patron:<user id>.

Holder::parse

pub fn parse(text: &str) -> Option<Self>

Parses stored holder text; None for any other shape.

Implements: Clone, Debug, Eq, Hash, Ord, PartialEq, PartialOrd

ListingError

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 than MAX_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

Functions

stored_marketplace

pub fn stored_marketplace(raw: &str) -> String

The stored spelling of a marketplace a source reported: trimmed, lower-cased, and DEFAULT_MARKETPLACE when blank.

stored_product_id

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.

work_match_key

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.

Arguments

  • title - Work title (decoded, any case).
  • authors - Author display names.

Returns

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.

canonical_language

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.

Arguments

  • raw - The language as a store or a stored row spells it.

Returns

The canonical code.

Constants

DEFAULT_MARKETPLACE

pub const DEFAULT_MARKETPLACE: &str = "us";

The marketplace a listing that names none is sold in.

MAX_TEXT_BYTES

pub const MAX_TEXT_BYTES: usize = 4096;

Longest text field accepted, in bytes.

MAX_IDENTIFIERS

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.

MAX_CREDITS

pub const MAX_CREDITS: usize = 128;

Most credits one listing may carry.

MAX_SERIES

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