bookclerk_storefront
Types storefront guests share with the host.
Native storefront guests (Libro.fm, Chirp, GraphicAudio, …) and the host
crates that talk to them. A guest reaches the library only through the
plugin ABI, so this crate carries the storefront DTOs, the conversions to
and from the typed ABI (abi), the listing / record helpers and the
text normalization both sides apply, and nothing that opens a database.
It deliberately has no dependency on bookclerk-library,
bookclerk-config, an ORM, a SQL driver or OpenAPI, so a guest build
stays small. The host-only half (the ContentSource trait, the source
registry, DownloadOptions, FetchOptions and the
conversions to library rows) lives in bookclerk-source, which
re-exports the storefront DTOs, ABI conversions and listing / record
helpers. Host code gets the text and content-kind helpers from
bookclerk-library, which re-exports them from here.
Product narrative: docs/plugins/README.md. Style: docs/contributing/code-documentation.md.
| Item | Kind | Summary |
|---|---|---|
SourceBrand |
struct | Visual identity for a content source in the connect portal. |
CatalogHit |
struct | Neutral catalog / candidate hit (no store crate types). |
CatalogSearchOpts |
struct | Options for the host's ContentSource::search_catalog. |
ConfigOptionValue |
struct | One allowed value for a SourceConfigOption. |
ExpandSeed |
struct | Seed for related / series / author expansion. |
ImportCredentialsOptions |
struct | Options for the host's ContentSource::import_credentials. |
LoginOptions |
struct | Options for interactive / CLI login. |
PlainAudioPart |
struct | One DRM-free audio part (chapter file or single book). |
PlainFetch |
struct | DRM-free fetch result. Sources that use DRM decrypt inside the plugin and return clear media here — the host never sees ciphertext or keys. |
PricedAnswer |
struct | A store's answer to one purchase-hint query, with any title-search records. |
PricedListing |
struct | One priced listing a title search matched, with its catalog record. |
PurchaseHintOpts |
struct | Options for the host's ContentSource::purchase_hint. |
ScanOptions |
struct | Options for a library scan. |
ScanSummary |
struct | Summary of a scan run. |
SourceAccount |
struct | Account discovered or created by a content source. |
SourceConfigOption |
struct | One source-native setting a storefront declares for its plugin instance. |
SourcePurchaseHint |
struct | URL + optional live price for one storefront edition. |
SourceError |
enum | Errors from content-source auth, scan, or fetch. |
CatalogSearchField |
enum | Optional role / facet for the host's ContentSource::search_catalog. |
CatalogSearchSort |
enum | Sort mode for the host's ContentSource::search_catalog. |
CatalogSortDir |
enum | Ascending / descending for catalog search host re-rank. |
OAuthProgress |
enum | Progress events for interactive OAuth login (portal / CLI). |
is_throttle_reason |
function | True when a store's refusal text says the account is being throttled (rate limited) rather than refused outright. |
default_preferred_language |
function | Preferred language for Discover when the client omits one. |
language_rank |
function | Rank a hit's language relative to the preferred code. |
audio_extension |
function | Prefer byte sniffing, then Content-Type, then URL path; default when all fail. |
extension_from_bytes |
function | Guess an audio extension from magic bytes (infer), with AAC/MP3 fallbacks. |
extension_from_content_type |
function | Map a Content-Type header (parameters stripped) to an audio extension. |
extension_from_url |
function | Guess an audio file extension from a URL path (query/fragment stripped). |
Result |
type alias | Result alias for content-source operations. |
SourceFetch |
type alias | Result of fetching a title for acquire (always clear media). |
DEFAULT_CATALOG_SEARCH_LIMIT |
constant | Hits a storefront returns from one catalog search when the caller leaves the limit at 0. |
content_kind::is_episodecontent_kind::is_podcast_parentlanguage::normalize_languagetext::decode_html_entitiestext::decode_html_entities_cowtext::decode_html_entities_in_placetext::decode_html_entities_opttext::decode_html_entities_opt_in_placetext::str_maybe_html_entitytypes::ChapterKindtypes::PriceLookup
abi: Conversions between host storefront types and the typed Cap'n Proto plugin ABI (bookclerk_plugin_abi).content_kind: Content-kind labels storefronts report for podcast shows and episodes.listing: Plugin ABI records as resolver listing drafts.records: Builders and flat views for the structured bibliographic records thatScanBookandCatalogHitcarry on the plugin ABI.text: Text normalization for storefront / catalog metadata.
pub struct SourceBrand {
pub id: &'static str,
pub name: &'static str,
pub bg: &'static str,
pub fg: &'static str,
pub accent: &'static str,
pub icon_url: &'static str,
}
Visual identity for a content source in the connect portal.
Fields
id: Stable plugin id matching the host'sContentSource::id(audible, …).name: Human-facing store name shown on the connect button.bg: CSS background color (hex) for the portal button.fg: CSS foreground / text color (hex) for the portal button.accent: CSS accent color (hex) for focus / highlights.icon_url: Remote favicon / app-icon URL (not stored in-repo).
pub fn logo_href(&self) -> &'static str
Favicon / app-icon URL used as the portal button logo (href).
Implements: Clone, Copy, Debug, Eq, PartialEq, Serialize
pub struct CatalogHit {
pub product_id: String,
pub title: String,
pub url: Option<String>,
pub cover_url: Option<String>,
pub origin: String,
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 work_kind: WorkKind,
pub expression_kind: ExpressionKind,
pub media_kind: MediaKind,
pub identifiers: Vec<Identifier>,
pub credits: Vec<Credit>,
pub series_entries: Vec<SeriesEntry>,
pub parent_product_id: Option<String>,
pub rank_hint: Option<u32>,
}
Neutral catalog / candidate hit (no store crate types).
Identity fields are required; bibliographic extras and list price are filled when a storefront’s search/expand payload already includes them (avoids a second Audnexus / purchase-hint round-trip for Discover detail).
Fields
product_id: Store-native product / title id (ASIN, ISBN, UUID, …).title: Display title for the work.url: Canonical storefront product URL when available.cover_url: Public cover image URL when the storefront provides one.origin: How this was found (related,series,author,search,top_deals, …).subtitle: Subtitle / secondary title line when the storefront provides one.description: Marketing / synopsis text from the storefront.publisher: Publisher imprint name when known.length_minutes: Runtime in whole minutes when the storefront reports duration.published_at: ISO-8601 / store release date string when known.categories: Genre / subject labels (;-separated).language: Content language (BCP-47 or storefront display name).price_cents: List / deal price from the same catalog payload (optional).currency: ISO 4217 currency code forSelf::price_centswhen priced.price_label: Pre-formatted price string for UI (e.g.$14.95).rating_overall: Community overall rating (0–5) when the storefront returned it.rating_count: Number of star ratings backingSelf::rating_overallwhen known.is_abridged:Some(true)when the storefront marks the title abridged;Some(false)for unabridged;Nonewhen unknown.is_explicit:Some(true)when the storefront marks the edition explicit (adult) content;Some(false)when it marks it clean;Nonewhen unknown.work_kind: Kind of work the hit is.expression_kind: How the work is realised in this edition.media_kind: Form of this edition; print and ebook hits are never acquired.identifiers: External identifiers (ISBN, ASIN, OpenLibrary ids).credits: Credited contributors in billing order.series_entries: Series the work belongs to.parent_product_id: Product id of the parent podcast show, for a podcast episode.rank_hint: The storefront's own 1-based rank for a catalog search hit across all result pages (seeCatalogSearchOpts::rank_hint);Nonewhen the store does not rank its results. Catalog search merges stores by it.
pub fn decode_html_entities(self) -> Self
Decode HTML entities in human-readable metadata fields.
Storefronts (notably Libro.fm) sometimes return Memory's Blade-style
titles; normalize before discover merge / UI display.
No-op (no allocations) when no field contains &.
pub fn authors(&self) -> Option<String>
Author names joined for the flat view; None when none is credited.
pub fn narrators(&self) -> Option<String>
Narrator names joined for the flat view; None when none is credited.
pub fn asin(&self) -> Option<String>
Amazon ASIN when the hit carries one.
pub fn asin_in(&self, marketplace: &str) -> Option<String>
ASIN for marketplace, falling back to an unscoped ASIN and then to
any ASIN the hit carries.
pub fn isbn(&self) -> Option<String>
ISBN when the hit carries one.
pub fn series(&self) -> Option<String>
Name of the first series the hit belongs to.
pub fn series_index(&self) -> Option<String>
Position label in the first series the hit belongs to.
Implements: Clone, Debug, Default, Deserialize<'de>, From<CatalogHit>, Serialize
pub struct CatalogSearchOpts {
pub query: String,
pub region: String,
pub limit: usize,
pub page: u32,
pub sort: CatalogSearchSort,
pub field: Option<CatalogSearchField>,
pub language: Option<String>,
}
Options for the host's ContentSource::search_catalog.
Fields
query: Free-text or facet search string.region: Marketplace / catalog region (us,uk, …); empty = plugin default.limit: Maximum hits to return;0meansDEFAULT_CATALOG_SEARCH_LIMIT(read it throughCatalogSearchOpts::effective_limit).page: 1-based page index for storefronts that support paging (default 1).sort: Preferred upstream / merge sort.field: When set, prefer storefront-native search for this facet.language: Preferred content language (BCP-47 primary or display name); soft-prioritize.
pub fn effective_limit(&self) -> usize
The number of hits to return: CatalogSearchOpts::limit, or
DEFAULT_CATALOG_SEARCH_LIMIT when the caller left it at 0.
A hit count of at least 1.
pub fn rank_hint(&self, index: usize) -> u32
1-based rank of the hit at index on this search's page, counted
across every page of Self::effective_limit hits (page 2 of 20-hit
pages starts at 21).
A storefront whose search order is meaningful for the requested sort
stores it in CatalogHit::rank_hint, so catalog search can merge
stores without naming any of them. Saturates at u32::MAX.
index- 0-based position of the hit within this page.
The rank, never 0 (0 means unranked on the wire).
pub fn stamp_rank_hints(&self, hits: &mut [CatalogHit])
Stamps Self::rank_hint on each hit of one search page, in order.
hits- The page's hits in the storefront's own order.
Implements: Clone, Debug, Default, From<&CatalogSearchOpts>, From<SearchCatalogParams>
pub struct ConfigOptionValue {
pub id: &'static str,
pub label: &'static str,
}
One allowed value for a SourceConfigOption.
Fields
id: Stored setting value (high,m4b,web, …).label: Operator-facing display name for this choice in Settings / CLI help.
Implements: Clone, Copy, Debug, Eq, PartialEq
pub struct ExpandSeed {
pub source: String,
pub product_id: String,
pub title: String,
pub authors: Option<String>,
pub narrators: Option<String>,
pub series: Option<String>,
pub series_asin: Option<String>,
pub asin: Option<String>,
pub isbn: Option<String>,
pub region: String,
}
Seed for related / series / author expansion.
Fields
source: Source id of the seed title (chirp,audible, …).product_id: Store-native product id of the owned / seed title.title: Display title used for related/series/author expansion queries.authors: Author names from the seed library row.narrators: Narrator names from the seed library row.series: Series name from the seed library row.series_asin: Parent Audible series ASIN when known (from library metadata).asin: Amazon ASIN when known for Audible-related expansion.isbn: ISBN when known for cross-store matching.region: Marketplace / catalog region (us,uk, …).
Implements: Clone, Debug
pub struct ImportCredentialsOptions {
pub libation_accounts: bool,
pub mkb79: bool,
pub label: Option<String>,
pub force: bool,
}
Options for the host's ContentSource::import_credentials.
Fields
libation_accounts: Treat input as classic LibationAccountsSettings.json.mkb79: Import mkb79 / audible-cli legacy auth JSON.label: Destination display label / filename stem.force: Overwrite an existing credential.
Implements: Clone, Debug, Default
pub struct LoginOptions {
pub marketplace: String,
pub label: Option<String>,
pub email: Option<String>,
pub password: Option<String>,
pub force: bool,
pub callback_bind: Option<String>,
pub external: bool,
pub response_url: Option<String>,
pub show_qr: bool,
pub timeout_secs: Option<u64>,
pub extra: Value,
}
Options for interactive / CLI login.
Fields
marketplace: Target marketplace / region for login (us,uk, …); empty = plugin default.label: Optional nickname stored with the new account credentials.email: Email/password sources; ignored for OAuth.password: Email/password sources; ignored for OAuth.force: When true, overwrite an existing credential blob for the same account.callback_bind: Optional OAuth callback bind (host:port) for portal / reverse-proxy use.external: External / paste-redirect OAuth instead of a local callback server.response_url: Pre-supplied OAuth redirect URL (withSelf::external).show_qr: Emit a terminal QR for the authorize URL when the source supports it.timeout_secs: Seconds to wait for OAuth callback capture (source-defined default whenNone).extra: Store-specific knobs (audible_username,ascii_qr, …). Guests may ignore unknowns.
Implements: Clone, Debug, Default, From<LoginParams>
pub struct PlainAudioPart {
pub path: PathBuf,
pub title: Option<String>,
pub duration_ms: Option<u64>,
}
One DRM-free audio part (chapter file or single book).
Fields
path: Absolute path to a clear (DRM-free) audio file on disk.title: Optional chapter / part title for packaging and metadata.duration_ms: Duration in milliseconds when known.
Implements: Clone, Debug
pub struct PlainFetch {
pub parts: Vec<PlainAudioPart>,
pub m4b_path: Option<PathBuf>,
pub cover_path: Option<PathBuf>,
pub chapters: Vec<(String, u64)>,
pub chapter_kind: ChapterKind,
pub pdf_url: Option<String>,
}
DRM-free fetch result. Sources that use DRM decrypt inside the plugin and return clear media here — the host never sees ciphertext or keys.
Fields
parts: Ordered clear audio parts (single file or per-chapter downloads).m4b_path: Pre-built M4B from the store / plugin when available.cover_path: Absolute path to a downloaded cover image when available.chapters: Chapter titles paired with start offsets in milliseconds.chapter_kind: Whatchaptersmarks: literary chapters, track boundaries, or unknown.pdf_url: Companion PDF download URL when the store exposes one.
Implements: Clone, Debug, From<PlainFetch>, TryFrom<PlainFetch>
pub struct PricedAnswer {
pub hint: Option<SourcePurchaseHint>,
pub records: Vec<PricedListing>,
}
A store's answer to one purchase-hint query, with any title-search records.
Fields
hint: The store's own pick;Nonewhen it found nothing.records: Every priced listing a title search matched, for the host to place. Empty for identifier lookups and for stores that return no records.
pub fn decode_html_entities(self) -> Self
Decode HTML entities in every hint and record (no-op when no &).
Implements: Clone, Debug, Default, Deserialize<'de>, From<Option<SourcePurchaseHint>>, From<PricedAnswer>, From<PurchaseHintResult>, Serialize
pub struct PricedListing {
pub record: CatalogHit,
pub hint: SourcePurchaseHint,
}
One priced listing a title search matched, with its catalog record.
A store answering a PriceLookup::Title query returns every listing the
search found, so the host can place each one in the library model (by
identifiers, credits and kinds) and keep only the recording it asked for.
Fields
record: The listing's catalog record: identifiers, credits, kinds, language.hint: Its purchase link and prices.
Implements: Clone, Debug, Default, Deserialize<'de>, Serialize
pub struct PurchaseHintOpts {
pub product_id: Option<String>,
pub title: Option<String>,
pub authors: Option<String>,
pub asin: Option<String>,
pub isbn: Option<String>,
pub region: String,
pub with_price: bool,
pub lookup: PriceLookup,
}
Options for the host's ContentSource::purchase_hint.
Fields
product_id: Preferred store-native product id when already known.title: Title used to disambiguate whenproduct_idis absent.authors: Author names used to disambiguate catalog lookups.asin: Amazon ASIN used for Audible / cross-store hints.isbn: ISBN used for cross-store hints.region: Marketplace / catalog region (us,uk, …); empty = plugin default.with_price: When true, resolve live price if the source can.lookup: How the host asks the store to find the title (product id, exact ISBN or ASIN, or a title search that returns records);Unspecifiedleaves the store free to use any field.
Implements: Clone, Debug, Default, From<&PurchaseHintOpts>, From<PurchaseHintParams>
pub struct ScanOptions {
pub accounts: Vec<String>,
pub page_size: u32,
pub import_episodes: bool,
pub import_plus_titles: bool,
pub cancel: Option<Arc<AtomicBool>>,
}
Options for a library scan.
Fields
accounts: Limit to specific account nicknames / ids.page_size: Upstream library page size (titles per HTTP page; default 50).import_episodes: Import podcast episodes — consumed by plugins that support it.import_plus_titles: Import catalog Plus / non-owned titles — consumed by plugins that support it.cancel: Cooperative cancel checked between sources and pages.
pub fn is_cancelled(&self) -> bool
True when a job fence asked this scan to stop.
Implements: Clone, Debug, Default
pub struct ScanSummary {
pub accounts: usize,
pub books_upserted: usize,
pub pages: u32,
pub skipped_disabled: usize,
pub removed: usize,
pub warnings: Vec<String>,
}
Summary of a scan run.
Fields
-
accounts: Number of accounts successfully scanned in this run. -
books_upserted: Library rows inserted or updated. -
pages: Upstream library pages fetched across all accounts. -
skipped_disabled: Accounts skipped becausecrate::SourceAccount::scan_enabledwas false. -
removed: Titles the storefronts reported gone from their accounts (delta passes). Counted only; holdings are not removed yet. -
warnings: Plugin keys skipped because more than one instance is registered.Other sources in the same scan still run. Accounts stay keyed by storefront id, so those keys are not scanned twice.
pub fn merge(&mut self, other: &Self)
Merge another source's summary into this one.
Implements: Clone, Debug, Default
pub struct SourceAccount {
pub account_id: String,
pub source: String,
pub marketplace: String,
pub label: Option<String>,
pub scan_enabled: bool,
}
Account discovered or created by a content source.
Fields
account_id: Stable account id stored in the library (often email or store user id).source: Canonical plugin id (audible,libro, …).marketplace: Store marketplace / region code (us,uk, …).label: Optional operator-facing nickname for CLI / UI selection.scan_enabled: When false, scheduled / bare scans skip this account (explicit--accountstill includes it).
Implements: Clone, Debug, Deserialize<'de>, From<SourceAccount>, Serialize
pub struct SourceConfigOption {
pub key: &'static str,
pub label: &'static str,
pub values: &'static [ConfigOptionValue],
}
One source-native setting a storefront declares for its plugin instance.
Fields
key: Setting key in the plugin instance document (bitrate,container,access).label: Operator-facing display name for this knob in Settings.values: Closed set of allowed wire values forSelf::key.
Implements: Clone, Copy, Debug, Eq, PartialEq
pub struct SourcePurchaseHint {
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>,
}
URL + optional live price for one storefront edition.
Fields
product_id: Store-native product id for the hinted edition.title: Display title when the storefront returns one with the hint.url: Deep link to buy / open the title on the storefront.price_cents: Primary / best known sell price in minor units (prefer member when dual).currency: ISO 4217 currency code for the primary price.price_label: Pre-formatted primary price string for UI.list_price_cents: Non-member / list / retail price when the storefront shows dual pricing.list_price_label: Pre-formatted non-member / list price for dual-price storefronts.member_price_cents: Member / subscriber price when distinct from list.member_price_label: Pre-formatted member / subscriber price when distinct from list.
pub fn decode_html_entities(self) -> Self
Decode HTML entities in human-readable fields (no-op when no &).
Implements: Clone, Debug, Default, Deserialize<'de>, From<PurchaseHint>, From<SourcePurchaseHint>, Serialize
pub enum SourceError {
NoAccounts(String),
Auth(String),
Api(String),
RateLimited(Option<Duration>),
Io(Error),
Library(Box<dyn Error + Send + Sync + 'static>),
Other(Error),
}
Errors from content-source auth, scan, or fetch.
Variants
-
NoAccounts: No accounts are configured for this source (safe to skip in multi-source scan). -
Auth: Authentication or credential failure (operator-facing message). -
Api: Upstream store HTTP / protocol failure (operator-facing message). -
RateLimited: The store asked to be left alone for a while (HTTP 429 or its equivalent); the duration is itsRetry-After, when it sent one. -
Io: Local filesystem failure while caching or writing downloads. -
Library: Library database / secret-store failure on the host.Guests never open the library; the host converts its store errors into this variant (
bookclerk-libraryimplements theFrom). -
Other: Catch-all for plugin-internal failures wrapped asanyhow::Error.
pub fn from_rate_limit(status: u16, retry_after: Option<&str>) -> Option<Self>
Self::RateLimited from an HTTP status and Retry-After header,
when the status is 429; otherwise None.
status- The response status code.retry_after- TheRetry-Afterheader value: whole seconds, as stores send it (an HTTP date is ignored).
pub fn no_accounts(msg: impl Into<String>) -> Self
Construct Self::NoAccounts with an operator-facing message.
pub fn auth(msg: impl Into<String>) -> Self
Construct Self::Auth with an operator-facing message.
pub fn api(msg: impl Into<String>) -> Self
Construct Self::Api with an operator-facing message.
Implements: Debug, Display, Error, From<Error>, From<SourceError>
pub enum CatalogSearchField {
Author,
Narrator,
Series,
Genre,
}
Optional role / facet for the host's ContentSource::search_catalog.
Free-text Discover typeahead leaves this unset. Meta links (author, narrator,
series, genre) set it so storefronts that support scoped params (e.g. Audible
author= / narrator=) can return the right catalog slice.
Variants
Author: Scope search to titles by this author.Narrator: Scope search to titles narrated by this person.Series: Scope search to titles in this series.Genre: Scope search to this genre / category facet.
pub fn from_wire(raw: &str) -> Option<Self>
Parse a wire / query-string value (author, narrators, …).
pub fn as_wire(self) -> &'static str
Serialize to the portal / query-string wire id.
Implements: Clone, Copy, Debug, Deserialize<'de>, Eq, PartialEq, Serialize
pub enum CatalogSearchSort {
Relevance,
Popularity,
Rating,
Title,
Author,
Price,
Length,
}
Sort mode for the host's ContentSource::search_catalog.
Storefronts that lack a matching upstream sort ignore this (caller merges).
Variants
Relevance: Storefront relevance ranking (default).Popularity: AudibleBestSellerswhen available.Rating: AudibleAvgRatingwhen available.Title: Alphabetical by title (host or upstream).Author: Alphabetical by primary author (often host re-rank).Price: Catalog list/dealprice_cents(host re-rank; sparse on some stores).Length:length_minutes(host re-rank).
pub fn from_wire(raw: &str) -> Self
Parse a wire / query-string sort id (unknown → Self::Relevance).
pub fn as_wire(self) -> &'static str
Serialize to the portal / query-string wire id.
pub fn audible_products_sort_by(self) -> &'static str
Audible /1.0/catalog/products products_sort_by value.
pub fn audible_catalog_search_sort(self) -> &'static str
Audible /1.0/catalog/search sort (sort_option_id) value.
Prefer this endpoint for Discover keyword browse — /catalog/products
keyword/title filters often omit major titles that still resolve by ASIN.
Implements: Clone, Copy, Debug, Default, Deserialize<'de>, Eq, From<CatalogSearchSort>, From<CatalogSort>, PartialEq, Serialize
pub enum CatalogSortDir {
Asc,
Desc,
}
Ascending / descending for catalog search host re-rank.
Variants
Asc: Ascending order.Desc: Descending order (default for popularity / rating / price).
pub fn from_wire(raw: &str) -> Self
Parse a wire / query-string direction (asc / desc; unknown → Self::Desc).
pub fn as_wire(self) -> &'static str
Serialize to the portal / query-string wire id.
pub fn default_for_sort(sort: CatalogSearchSort) -> Self
Default direction when the client omits sort_dir.
Implements: Clone, Copy, Debug, Default, Deserialize<'de>, Eq, PartialEq, Serialize
pub enum OAuthProgress {
LoginUrl { url: String, qr: Option<String> },
CallbackListening { addr: String },
WaitingForCallback,
Completed { account_id: String },
}
Progress events for interactive OAuth login (portal / CLI).
Variants
LoginUrl: Browser URL the operator should open (optional pre-rendered QR text).url: Absolute HTTPS URL for the browser / QR payload.qr: Optional pre-rendered QR text for terminal UIs.
CallbackListening: Local callback server is listening (SSH port-forward hint).addr: Listen address (host:port) of the local redirect receiver.
WaitingForCallback: Waiting for the OAuth redirect / callback.Completed: Login finished; credentials are persisted foraccount_id.account_id: Account id stored after a successful login.
Implements: Clone, Debug
pub fn is_throttle_reason(reason: &str) -> bool
True when a store's refusal text says the account is being throttled (rate limited) rather than refused outright.
Stores rarely give throttling a code of its own (Audible's license
refusals do not), so this reads the words they use: throttled, rate
limit, too many requests, HTTP 429. Case is ignored; any other text,
including other limits such as a device or download limit, is not a
throttle. A storefront that answers true returns
SourceError::RateLimited, which pauses the whole account.
reason- The refusal text the store sent, untrusted.
Whether the text contains one of the throttle words.
pub fn default_preferred_language() -> &'static str
Preferred language for Discover when the client omits one.
pub fn language_rank(hit_language: Option<&str>, preferred: &str) -> u8
Rank a hit's language relative to the preferred code.
0— matches preferred1— unknown / missing2— other language
pub fn audio_extension(
url: &str,
bytes: Option<&[u8]>,
content_type: Option<&str>,
default: &'static str,
) -> &'static str
Prefer byte sniffing, then Content-Type, then URL path; default when all fail.
pub fn extension_from_bytes(bytes: &[u8]) -> Option<&'static str>
Guess an audio extension from magic bytes (infer), with AAC/MP3 fallbacks.
pub fn extension_from_content_type(content_type: &str) -> Option<&'static str>
Map a Content-Type header (parameters stripped) to an audio extension.
pub fn extension_from_url(url: &str) -> Option<&'static str>
Guess an audio file extension from a URL path (query/fragment stripped).
pub type Result<T> = Result<T, SourceError>;
Result alias for content-source operations.
pub type SourceFetch = PlainFetch;
Result of fetching a title for acquire (always clear media).
Historically a dual Encrypted/Plain enum; DRM is plugin-owned now, so this
is an alias of PlainFetch. Prefer PlainFetch in new code.
pub const DEFAULT_CATALOG_SEARCH_LIMIT: usize = 20;
Hits a storefront returns from one catalog search when the caller leaves
the limit at 0.
Generated from crates/bookclerk-storefront at main · View as Markdown