bookclerk_plugin_source_chirp

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

Last updated View as Markdown

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

Re-exports

Modules

  • guest: Guest-process helpers for the external Chirp source plugin.

Structs

ChirpAuthFile

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 GraphQL signIn (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 from signIn when present.
  • marketplace: Marketplace / locale hint stored for Bookclerk (defaults to us).
  • label: Optional operator-facing account label in Accounts UI.

ChirpAuthFile::account_id

pub fn account_id(&self) -> &str

Stable account id: prefer Chirp user id, else email.

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

Audiobook

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>

AuthorCatalog

pub struct AuthorCatalog {
    pub author: CatalogAuthor,
    pub audiobooks: Vec<CatalogAudiobook>,
}

Author summary expansion result.

Fields

  • author: Author.
  • audiobooks: Audiobooks.

Implements: Clone, Debug

CatalogAudiobook

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

CatalogAudiobook::title

pub fn title(&self) -> String

Title.

CatalogAudiobook::series_name

pub fn series_name(&self) -> Option<String>

Series name.

Implements: Clone, Debug, Deserialize<'de>

CatalogAuthor

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>

CatalogSeries

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>

ChirpClient

pub struct ChirpClient {
    /* private fields */
}

Authenticated Chirp GraphQL helper.

ChirpClient::new

pub fn new(graphql_url: impl Into<String>) -> Self

Constructs a new instance with default or provided parameters.

ChirpClient::with_http

pub fn with_http(self, http: HttpClient) -> Self

With HTTP.

ChirpClient::with_token

pub fn with_token(self, token: impl Into<String>) -> Self

With token.

ChirpClient::access_token

pub fn access_token(&self) -> Option<&str>

Access token.

ChirpClient::graphql_url

pub fn graphql_url(&self) -> &str

Graphql URL.

ChirpClient::login

pub async fn login(&mut self, email: &str, password: &str) -> Result<SignInUser>

GraphQL signIn mutation.

Errors

Returns an error when the operation fails.

ChirpClient::library_page

pub async fn library_page(&self, page: u32, page_size: u32) -> Result<Vec<LibraryItem>>

Paginated owned library (currentUserAudiobooks).

Errors

Returns an error when the operation fails.

ChirpClient::audiobook

pub async fn audiobook(&self, id: &str) -> Result<Audiobook>

Full audiobook with track mediaUrls.

Errors

Returns an error when the operation fails.

ChirpClient::audiobook_pricing

pub async fn audiobook_pricing(&self, id: &str) -> Result<Option<ChirpProductPricing>>

Live deal / list pricing for a Chirp audiobook (public GraphQL).

Errors

Returns an error when the operation fails.

ChirpClient::audiobook_pricings

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.

Errors

Returns an error when the request fails, including ChirpError::RateLimited when Chirp asks to slow down.

ChirpClient::search_catalog

pub async fn search_catalog(
    &self,
    query: &str,
    page: u32,
    page_size: u32,
) -> Result<Vec<CatalogAudiobook>>

Catalog search (audiobooks(query:)) — no auth required.

Errors

Returns an error when the operation fails.

ChirpClient::related_audiobooks

pub async fn related_audiobooks(&self, id: &str) -> Result<RelatedCatalog>

Related titles for a Chirp audiobook id — no auth required.

Errors

Returns an error when the operation fails.

ChirpClient::series_catalog

pub async fn series_catalog(&self, slug: &str) -> Result<Option<SeriesCatalog>>

Series catalog by slug (mistborn-audiobooks, …) — no auth required.

Errors

Returns an error when the operation fails.

ChirpClient::author_summary

pub async fn author_summary(&self, slug: &str) -> Result<Option<AuthorCatalog>>

Author summary titles by slug — no auth required.

Errors

Returns an error when the operation fails.

ChirpClient::typeahead

pub async fn typeahead(&self, search_term: &str) -> Result<TypeaheadCatalog>

Typeahead for author slug resolution and quick title hits — no auth required.

Errors

Returns an error when the operation fails.

ChirpClient::resolve_author_slug

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.

Errors

Returns an error when the operation fails.

ChirpClient::resolve_series_catalog

pub async fn resolve_series_catalog(
    &self,
    series_name: &str,
) -> Result<Option<SeriesCatalog>>

Try common Chirp series slug forms derived from a series title.

Errors

Returns an error when the operation fails.

ChirpClient::top_deals

pub async fn top_deals(&self, count: u32) -> Result<Vec<CatalogAudiobook>>

Current Chirp top deals — no auth required.

Errors

Returns an error when the operation fails.

ChirpClient::free_deals

pub async fn free_deals(&self) -> Result<Vec<CatalogAudiobook>>

Current Chirp free deals — no auth required.

Errors

Returns an error when the operation fails.

ChirpClient::download_to_file

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.

Returns

The file's length in bytes.

Errors

Returns ChirpError::Download when the store refuses the file or the transfer keeps failing.

Implements: Clone, Debug, Default

ChirpProductPricing

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>

LibraryItem

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>

RelatedCatalog

pub struct RelatedCatalog {
    pub related: Vec<CatalogAudiobook>,
    pub series: Option<CatalogSeries>,
}

Related-audiobook expansion result.

Fields

  • related: Related.
  • series: Series.

Implements: Clone, Debug

SeriesCatalog

pub struct SeriesCatalog {
    pub series: CatalogSeries,
    pub audiobooks: Vec<CatalogAudiobook>,
}

Series page expansion result.

Fields

  • series: Series.
  • audiobooks: Audiobooks.

Implements: Clone, Debug

Track

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>

TypeaheadCatalog

pub struct TypeaheadCatalog {
    pub audiobooks: Vec<CatalogAudiobook>,
    pub authors: Vec<CatalogAuthor>,
}

Typeahead hits.

Fields

  • audiobooks: Audiobooks.
  • authors: Authors.

Implements: Clone, Debug, Default

ChirpSource

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.

ChirpSource::new

pub fn new() -> Self

Returns a Chirp source aimed at the production GraphQL endpoint.

ChirpSource::with_graphql_url

pub fn with_graphql_url(graphql_url: impl Into<String>) -> Self

Overrides the GraphQL endpoint (tests / staging).

ChirpSource::from_config

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.

ChirpSource::search_catalog

pub async fn search_catalog(&self, opts: &CatalogSearchOpts) -> Result<Vec<CatalogHit>>

Searches the public catalog.

Errors

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.

ChirpSource::expand_candidates

pub async fn expand_candidates(
    &self,
    seed: &ExpandSeed,
    limit: usize,
) -> Result<Vec<CatalogHit>>

Finds up to limit titles related to seed (same author, series, …).

Errors

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.

ChirpSource::purchase_hint

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.

Errors

As Self::purchase_answer.

ChirpSource::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.

Errors

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.

ChirpSource::purchase_hints

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.

Errors

As Self::purchase_answers.

ChirpSource::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.

Errors

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.

ChirpSource::list_deals

pub async fn list_deals(&self, limit: usize) -> Result<Vec<CatalogHit>>

Lists up to limit titles on the storefront's current deals shelf.

Errors

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

Enums

ChirpError

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: GraphQL signIn or token use failed.
  • NoAccounts: No Chirp accounts are configured (safe to skip in multi-source scan).
  • AccountNotFound: Requested account id is not present in encrypted_secrets.
  • Api: Upstream GraphQL / HTTP API error.
  • RateLimited: Chirp answered 429; the duration is its Retry-After, when sent.
  • Download: Title download or packaging failed.
  • Io: Local filesystem I/O while reading or writing cache files.
  • Other: Unexpected failure wrapped from anyhow.

ChirpError::auth

pub fn auth(msg: impl Into<String>) -> Self

Builds an Self::Auth error from a displayable message.

ChirpError::no_accounts

pub fn no_accounts(msg: impl Into<String>) -> Self

Builds a Self::NoAccounts error (multi-source scan may skip this store).

ChirpError::api

pub fn api(msg: impl Into<String>) -> Self

Builds an Self::Api error from a displayable message.

ChirpError::download

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>

Functions

chirp_slug_candidates

pub fn chirp_slug_candidates(name: &str) -> Vec<String>

Slug guesses for Chirp series(slug:) / author(slug:).

fetch_title_materials

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.

Errors

Returns an error when the operation fails.

audiobook_to_scan_book

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.

collect_account_books

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

Errors

Returns an error when the operation fails.

fetch_account_page

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

Arguments

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

Returns

The page's playable titles and the next page number, None on the last page (a short or empty page).

Errors

Returns an error when the request fails.

Type aliases

Result

pub type Result<T> = Result<T, ChirpError>;

Result alias for Chirp auth, sync, and download operations.

Constants

DEFAULT_GRAPHQL_URL

pub const DEFAULT_GRAPHQL_URL: &str = "https://api.chirpbooks.com/api/graphql";

Android Mockingjay GraphQL endpoint.

CHIRP_SOURCE_ID

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