bookclerk_plugin_source_chirp
Chirp content source: GraphQL auth, library sync, and DRM-free download.
Uses the reverse-engineered Android Mockingjay GraphQL API
(https://api.chirpbooks.com/api/graphql).
| Item | Kind | Summary |
|---|---|---|
ChirpAuthFile |
struct | Credential envelope for one Chirp account. |
Audiobook |
struct | Chirp audiobook metadata (+ optional tracks). |
AuthorCatalog |
struct | Author summary expansion result. |
CatalogAudiobook |
struct | Catalog-oriented audiobook (search / related / series). |
CatalogAuthor |
struct | Chirp author metadata. |
CatalogSeries |
struct | Chirp series metadata. |
ChirpClient |
struct | Authenticated Chirp GraphQL helper. |
ChirpProductPricing |
struct | Live Chirp storefront pricing (audiobook.currentProduct). |
LibraryItem |
struct | One currentUserAudiobooks row. |
RelatedCatalog |
struct | Related-audiobook expansion result. |
SeriesCatalog |
struct | Series page expansion result. |
Track |
struct | One downloadable / playable track. |
TypeaheadCatalog |
struct | Typeahead hits. |
ChirpSource |
struct | Chirp catalog client used by the guest's discovery entrypoints. |
ChirpError |
enum | Failures from Chirp GraphQL sign-in, library listing, or DRM-free download. |
chirp_slug_candidates |
function | Slug guesses for Chirp series(slug:) / author(slug:). |
fetch_title_materials |
function | Fetch one audiobook id into cache_dir via AndroidSingleAudiobook track URLs. |
audiobook_to_scan_book |
function | Map a Chirp audiobook to a structured scan row. Chirp returns one display string per role, so names are split with records::credits_from_display. |
collect_account_books |
function | Fetch all library pages for one client and collect books (no DB writes). |
fetch_account_page |
function | Fetch one Chirp library page as scan rows (no DB writes). |
Result |
type alias | Result alias for Chirp auth, sync, and download operations. |
DEFAULT_GRAPHQL_URL |
constant | Android Mockingjay GraphQL endpoint. |
CHIRP_SOURCE_ID |
constant | Describe / config id for this store (chirp). |
guest::guest_fetch_titleguest::guest_fetch_title_rpcguest::guest_loginguest::guest_login_rpcguest::guest_scan_pageguest::resolve_graphql_url
guest: Guest-process helpers for the external Chirp source plugin.
pub struct ChirpAuthFile {
pub access_token: String,
pub web_token: Option<String>,
pub email: String,
pub user_id: Option<String>,
pub marketplace: String,
pub label: Option<String>,
}
Credential envelope for one Chirp account.
The guest returns it from login; the host seals it into encrypted_secrets
and passes it back on scan and fetch. Never written
to disk under Accounts/.
Fields
access_token: JWT from GraphQLsignIn(user.token).web_token: Longer-lived web JWT when present (user.webToken).email: Sign-in email used as fallback account id.user_id: Chirp user id fromsignInwhen present.marketplace: Marketplace / locale hint stored for Bookclerk (defaults tous).label: Optional operator-facing account label in Accounts UI.
pub fn account_id(&self) -> &str
Stable account id: prefer Chirp user id, else email.
Implements: Clone, Debug, Deserialize<'de>, Serialize
pub struct Audiobook {
pub id: String,
pub display_title: Option<String>,
pub sub_title: Option<String>,
pub display_authors: Option<String>,
pub display_narrators: Option<String>,
pub duration_ms: Option<u64>,
pub abridged: Option<bool>,
pub publisher: Option<String>,
pub released_on: Option<String>,
pub cover_url: Option<String>,
pub description: Option<String>,
pub tracks: Vec<Track>,
}
Chirp audiobook metadata (+ optional tracks).
Fields
id: Identifier.display_title: Display title.sub_title: Sub title.display_authors: Display authors.display_narrators: Display narrators.duration_ms: Duration ms.abridged: Abridged.publisher: Publisher.released_on: Released on.cover_url: Cover URL.description: Description.tracks: Tracks.
Implements: Clone, Debug, Deserialize<'de>
pub struct AuthorCatalog {
pub author: CatalogAuthor,
pub audiobooks: Vec<CatalogAudiobook>,
}
Author summary expansion result.
Fields
author: Author.audiobooks: Audiobooks.
Implements: Clone, Debug
pub struct CatalogAudiobook {
pub id: String,
pub display_title: Option<String>,
pub display_authors: Option<String>,
pub display_narrators: Option<String>,
pub url: Option<String>,
pub cover_url: Option<String>,
pub series_audiobook: Option<SeriesAudiobookRef>,
pub sub_title: Option<String>,
pub description: Option<String>,
pub publisher: Option<String>,
pub duration_ms: Option<u64>,
pub released_on: Option<String>,
pub language: Option<String>,
pub abridged: Option<bool>,
pub promoted_tags: Vec<CatalogTag>,
}
Catalog-oriented audiobook (search / related / series).
Fields
id: Identifier.display_title: Display title.display_authors: Display authors.display_narrators: Display narrators.url: URL.cover_url: Cover URL.series_audiobook: Series audiobook.sub_title: Sub title.description: Description.publisher: Publisher.duration_ms: Duration ms.released_on: Released on.language: Chirp display language (English,Spanish, …).abridged: Abridged.promoted_tags: Storefront genre chips (Thrillers,Crime Fiction & Mysteries, …).
pub fn title(&self) -> String
Title.
pub fn series_name(&self) -> Option<String>
Series name.
Implements: Clone, Debug, Deserialize<'de>
pub struct CatalogAuthor {
pub id: String,
pub name: String,
pub slug: String,
}
Chirp author metadata.
Fields
id: Identifier.name: Display or configuration name.slug: Slug.
Implements: Clone, Debug, Deserialize<'de>
pub struct CatalogSeries {
pub id: String,
pub name: String,
pub slug: String,
}
Chirp series metadata.
Fields
id: Identifier.name: Display or configuration name.slug: Slug.
Implements: Clone, Debug, Deserialize<'de>
pub struct ChirpClient {
/* private fields */
}
Authenticated Chirp GraphQL helper.
pub fn new(graphql_url: impl Into<String>) -> Self
Constructs a new instance with default or provided parameters.
pub fn with_http(self, http: HttpClient) -> Self
With HTTP.
pub fn with_token(self, token: impl Into<String>) -> Self
With token.
pub fn access_token(&self) -> Option<&str>
Access token.
pub fn graphql_url(&self) -> &str
Graphql URL.
pub async fn login(&mut self, email: &str, password: &str) -> Result<SignInUser>
GraphQL signIn mutation.
Returns an error when the operation fails.
pub async fn library_page(&self, page: u32, page_size: u32) -> Result<Vec<LibraryItem>>
Paginated owned library (currentUserAudiobooks).
Returns an error when the operation fails.
pub async fn audiobook(&self, id: &str) -> Result<Audiobook>
Full audiobook with track mediaUrls.
Returns an error when the operation fails.
pub async fn audiobook_pricing(&self, id: &str) -> Result<Option<ChirpProductPricing>>
Live deal / list pricing for a Chirp audiobook (public GraphQL).
Returns an error when the operation fails.
pub async fn audiobook_pricings(
&self,
ids: &[String],
) -> Result<HashMap<String, ChirpProductPricing>>
Live pricing for several audiobooks in one GraphQL request, by id.
Each id is an aliased audiobook(id:) field of one query, so a page
of cards costs one request. Ids Chirp does not know are absent.
Returns an error when the request fails, including
ChirpError::RateLimited when Chirp asks to slow down.
pub async fn search_catalog(
&self,
query: &str,
page: u32,
page_size: u32,
) -> Result<Vec<CatalogAudiobook>>
Catalog search (audiobooks(query:)) — no auth required.
Returns an error when the operation fails.
pub async fn related_audiobooks(&self, id: &str) -> Result<RelatedCatalog>
Related titles for a Chirp audiobook id — no auth required.
Returns an error when the operation fails.
pub async fn series_catalog(&self, slug: &str) -> Result<Option<SeriesCatalog>>
Series catalog by slug (mistborn-audiobooks, …) — no auth required.
Returns an error when the operation fails.
pub async fn author_summary(&self, slug: &str) -> Result<Option<AuthorCatalog>>
Author summary titles by slug — no auth required.
Returns an error when the operation fails.
pub async fn typeahead(&self, search_term: &str) -> Result<TypeaheadCatalog>
Typeahead for author slug resolution and quick title hits — no auth required.
Returns an error when the operation fails.
pub async fn resolve_author_slug(&self, author_name: &str) -> Result<Option<String>>
Resolve a Chirp author slug via typeahead (exact name match only).
Deliberately no substring fallback — short needles like "ann" would
otherwise resolve to unrelated authors and pollute candidate expansion.
Returns an error when the operation fails.
pub async fn resolve_series_catalog(
&self,
series_name: &str,
) -> Result<Option<SeriesCatalog>>
Try common Chirp series slug forms derived from a series title.
Returns an error when the operation fails.
pub async fn top_deals(&self, count: u32) -> Result<Vec<CatalogAudiobook>>
Current Chirp top deals — no auth required.
Returns an error when the operation fails.
pub async fn free_deals(&self) -> Result<Vec<CatalogAudiobook>>
Current Chirp free deals — no auth required.
Returns an error when the operation fails.
pub async fn download_to_file(&self, url: &str, dest: &Path) -> Result<u64>
Streams a track or cover URL to dest, resuming a dropped transfer
through the SDK's resumable download (bookclerk_plugin_sdk::download)
instead of holding the file in memory.
The file's length in bytes.
Returns ChirpError::Download when the store refuses the file or
the transfer keeps failing.
Implements: Clone, Debug, Default
pub struct ChirpProductPricing {
pub id: Option<String>,
pub discount_price: String,
pub discounted_price_cents: Option<i64>,
pub listing_price: Option<String>,
pub is_free_listing: bool,
pub hot_deal: bool,
pub purchase_url: Option<String>,
pub salable_in_current_country: Option<bool>,
}
Live Chirp storefront pricing (audiobook.currentProduct).
Fields
id: Identifier.discount_price: Discount price.discounted_price_cents: Discounted price cents.listing_price: Listing price.is_free_listing: Is free listing.hot_deal: Hot deal.purchase_url: Purchase URL.salable_in_current_country: Salable in current country.
Implements: Clone, Debug, Deserialize<'de>
pub struct LibraryItem {
pub id: String,
pub archived: Option<bool>,
pub playable: Option<bool>,
pub audiobook: Option<Audiobook>,
}
One currentUserAudiobooks row.
Fields
id: Identifier.archived: Archived.playable: Playable.audiobook: Audiobook.
Implements: Clone, Debug, Deserialize<'de>
pub struct RelatedCatalog {
pub related: Vec<CatalogAudiobook>,
pub series: Option<CatalogSeries>,
}
Related-audiobook expansion result.
Fields
related: Related.series: Series.
Implements: Clone, Debug
pub struct SeriesCatalog {
pub series: CatalogSeries,
pub audiobooks: Vec<CatalogAudiobook>,
}
Series page expansion result.
Fields
series: Series.audiobooks: Audiobooks.
Implements: Clone, Debug
pub struct Track {
pub id: String,
pub media_url: Option<String>,
pub chapter_number: Option<i64>,
pub part_number: Option<i64>,
pub duration_ms: Option<u64>,
pub offset_from_book_start_ms: Option<u64>,
pub display_name: Option<String>,
}
One downloadable / playable track.
Fields
id: Identifier.media_url: Media URL.chapter_number: Chapter number.part_number: Part number.duration_ms: Duration ms.offset_from_book_start_ms: Offset from book start ms.display_name: Display name.
Implements: Clone, Debug, Deserialize<'de>
pub struct TypeaheadCatalog {
pub audiobooks: Vec<CatalogAudiobook>,
pub authors: Vec<CatalogAuthor>,
}
Typeahead hits.
Fields
audiobooks: Audiobooks.authors: Authors.
Implements: Clone, Debug, Default
pub struct ChirpSource {
/* private fields */
}
Chirp catalog client used by the guest's discovery entrypoints.
Construct with ChirpSource::new; use ChirpSource::with_graphql_url
for wiremock / staging.
pub fn new() -> Self
Returns a Chirp source aimed at the production GraphQL endpoint.
pub fn with_graphql_url(graphql_url: impl Into<String>) -> Self
Overrides the GraphQL endpoint (tests / staging).
pub fn from_config(config: &Value) -> Self
Catalog client for the instance settings document config.
Uses the document's graphql_url override when it has one, the same
endpoint crate::guest::resolve_graphql_url gives sign-in, scans
and fetches, so a staging or mock endpoint reaches every entrypoint.
pub async fn search_catalog(&self, opts: &CatalogSearchOpts) -> Result<Vec<CatalogHit>>
Searches the public catalog.
Returns an error when a storefront request or its parse fails and the method cannot fall back. Some lookups fail soft and only yield fewer results (or none), so an empty result does not prove the store has none.
pub async fn expand_candidates(
&self,
seed: &ExpandSeed,
limit: usize,
) -> Result<Vec<CatalogHit>>
Finds up to limit titles related to seed (same author, series, …).
Returns an error when a storefront request or its parse fails and the method cannot fall back. Some lookups fail soft and only yield fewer results (or none), so an empty result does not prove the store has none.
pub async fn purchase_hint(
&self,
opts: &PurchaseHintOpts,
) -> Result<Option<SourcePurchaseHint>>
Resolves the storefront price and link for a title; None when not sold.
The bare-hint form of Self::purchase_answer.
pub async fn purchase_answer(&self, opts: &PurchaseHintOpts) -> Result<PricedAnswer>
Resolves a title's Chirp product and price, with every listing a title search found.
A known Chirp product id is priced as it is. Otherwise the title and
author go to the store's typeahead search, and up to
TITLE_RECORDS audiobooks come back as priced records (credits,
series, publisher, length and language) for the host to place. The
store's pick is the first one whose title matches, as before records
existed.
Returns bookclerk_storefront::SourceError::RateLimited when Chirp
asks to slow down. Other failed lookups are soft, so an empty answer
can also mean the store could not be reached, not only that the
title is not sold.
pub async fn purchase_hints(
&self,
opts: &[PurchaseHintOpts],
) -> Result<Vec<Option<SourcePurchaseHint>>>
Resolves purchase hints for several titles, pricing them in one aliased GraphQL request instead of one per card.
The bare-hint form of Self::purchase_answers.
pub async fn purchase_answers(
&self,
opts: &[PurchaseHintOpts],
) -> Result<Vec<PricedAnswer>>
Resolves several titles with each title search's records, pricing
every product found in one aliased GraphQL request per
PRICE_BATCH_IDS (50) instead of one per card.
Titles whose Chirp product id is known resolve first, without a
search; the rest are looked up by title until the 5 s RESOLVE_BUDGET runs
out, and a title not tried by then answers nothing, which the host
does not take as an answer.
Returns bookclerk_storefront::SourceError::RateLimited when Chirp
asks to slow down, during a title lookup or the pricing query; other
failures leave the cards unpriced.
pub async fn list_deals(&self, limit: usize) -> Result<Vec<CatalogHit>>
Lists up to limit titles on the storefront's current deals shelf.
Returns an error when a storefront request or its parse fails and the method cannot fall back. Some lookups fail soft and only yield fewer results (or none), so an empty result does not prove the store has none.
Implements: Clone, Debug, Default
pub enum ChirpError {
Auth(String),
NoAccounts(String),
AccountNotFound(String),
Api(String),
RateLimited(Option<Duration>),
Download(String),
Io(Error),
Other(Error),
}
Failures from Chirp GraphQL sign-in, library listing, or DRM-free download.
Variants
Auth: GraphQLsignInor token use failed.NoAccounts: No Chirp accounts are configured (safe to skip in multi-source scan).AccountNotFound: Requested account id is not present inencrypted_secrets.Api: Upstream GraphQL / HTTP API error.RateLimited: Chirp answered 429; the duration is itsRetry-After, when sent.Download: Title download or packaging failed.Io: Local filesystem I/O while reading or writing cache files.Other: Unexpected failure wrapped fromanyhow.
pub fn auth(msg: impl Into<String>) -> Self
Builds an Self::Auth error from a displayable message.
pub fn no_accounts(msg: impl Into<String>) -> Self
Builds a Self::NoAccounts error (multi-source scan may skip this store).
pub fn api(msg: impl Into<String>) -> Self
Builds an Self::Api error from a displayable message.
pub fn download(msg: impl Into<String>) -> Self
Builds a Self::Download error from a displayable message.
Implements: Debug, Display, Error, From<ChirpError>, From<Error>
pub fn chirp_slug_candidates(name: &str) -> Vec<String>
Slug guesses for Chirp series(slug:) / author(slug:).
pub async fn fetch_title_materials(
client: &ChirpClient,
audiobook_id: &str,
cache_dir: &Path,
) -> Result<PlainFetch>
Fetch one audiobook id into cache_dir via AndroidSingleAudiobook track URLs.
Returns an error when the operation fails.
pub fn audiobook_to_scan_book(
book: &Audiobook,
account_id: &str,
marketplace: &str,
) -> ScanBook
Map a Chirp audiobook to a structured scan row. Chirp returns one display
string per role, so names are split with records::credits_from_display.
pub async fn collect_account_books(
client: &ChirpClient,
account_id: &str,
marketplace: &str,
page_size: u32,
) -> Result<(Vec<ScanBook>, u32)>
Fetch all library pages for one client and collect books (no DB writes).
Returns an error when the operation fails.
pub async fn fetch_account_page(
client: &ChirpClient,
account_id: &str,
marketplace: &str,
page: u32,
page_size: u32,
) -> Result<(Vec<ScanBook>, Option<u32>)>
Fetch one Chirp library page as scan rows (no DB writes).
client- Authenticated Chirp client.account_id- Account the rows belong to.marketplace- Marketplace stamped on every row.page- 1-based library page.page_size- Items per page (at least 1).
The page's playable titles and the next page number, None on the last
page (a short or empty page).
Returns an error when the request fails.
pub type Result<T> = Result<T, ChirpError>;
Result alias for Chirp auth, sync, and download operations.
pub const DEFAULT_GRAPHQL_URL: &str = "https://api.chirpbooks.com/api/graphql";
Android Mockingjay GraphQL endpoint.
pub const CHIRP_SOURCE_ID: &str = "chirp";
Describe / config id for this store (chirp).
Generated from crates/bookclerk-plugins/optional/source-chirp at main · View as Markdown