bookclerk_plugin_source_graphicaudio
GraphicAudio content source: auth, library sync, and DRM-free download.
Access paths (see docs/contributing/research/source-candidates.md), selected by
the access plugin setting (default web):
- Browser Player (
/library) — Magento session + CloudFront cookies - Magento ZIP (
My Downloadable Products) — opt-in (access = "zip") - Access App Retrofit API (
/access) — opt-in device activation (access = "device")
| Item | Kind | Summary |
|---|---|---|
GraphicAudioAuthFile |
struct | Credential envelope for one GraphicAudio account. |
MagentoCatalogProduct |
struct | One Magento catalog product (grid / related / product page). |
DownloadLinks |
struct | Lo/Hi download URLs from api/links. |
GraphicAudioClient |
struct | Authenticated GraphicAudio HTTP helper. |
Product |
struct | One library / sample product from api/products. |
TitleFetchRequest |
struct | Parameters for fetch_title_with_mode. |
DownloadableProduct |
struct | One row from My Downloadable Products. |
LibraryItem |
struct | One owned title from Browser Player content_library HTML. |
MagentoClient |
struct | Magento customer session + cookie jar (including Browser Player CloudFront cookies). |
GraphicAudioSource |
struct | GraphicAudio catalog client used by the guest's discovery entrypoints. |
GraphicAudioError |
enum | Failures from Magento / Access App auth, library listing, or download. |
GraphicAudioAccess |
enum | How GraphicAudio fetches owned audio (the access plugin setting). |
GraphicAudioBitrate |
enum | GraphicAudio device encode preference (the bitrate plugin setting). |
GraphicAudioContainer |
enum | Preferred GraphicAudio ZIP SKU when GraphicAudioAccess::Zip. |
catalog_http_client |
function | Shared HTTP client for public Magento catalog pages. |
expand_from_product_id |
function | Expand a owned Magento product id into related + series siblings. |
expand_from_search |
function | Expand via Magento catalog search (series name or title). |
fetch_product_by_id |
function | Magento product page by numeric product id. |
fetch_series_page |
function | Fetch titles listed on a series category page (includes series-set SKUs). |
parse_catalog_grid |
function | Parse Magento product grid / related list items. |
parse_related_products |
function | Parse the Recommended / related products block on a product page. |
search_catalog |
function | Search Magento catalog; often redirects to a matching series page. |
search_catalog_page |
function | Like search_catalog with an optional Magento page index. |
parse_product_detail |
function | Reads one GraphicAudio product page as a catalog record. |
fetch_title_materials |
function | Password env (same as CLI login) for Magento ZIP / Browser Player. Fetch one product id into cache_dir via api/links Hi/Lo URLs. |
fetch_title_with_mode |
function | Fetch owned audio for one product using the configured access path only (no ZIP→web→device cascade). |
collect_account_books |
function | Collect owned titles for one account (no DB writes). |
product_to_scan_book |
function | Map a GraphicAudio product JSON object to a structured scan row. |
Result |
type alias | Result alias for GraphicAudio auth, sync, and download operations. |
DEFAULT_BASE_URL |
constant | Default API origin (no trailing slash after /access). |
LOGIN_PATH |
constant | Device activation / password login. |
PRODUCTS_PATH |
constant | Library + sample products listing. |
REMOVE_PATH |
constant | Forget a device activation (client_id form field). |
GA_ACCESS_ENV |
constant | Preferred env override (BOOKCLERK_GA_ACCESS); falls back to GA_FETCH_ENV. |
GA_FETCH_ENV |
constant | Env override for which GraphicAudio access path to use (legacy name). |
DEFAULT_STORE_URL |
constant | Default Magento storefront origin (no /access suffix). |
GRAPHICAUDIO_SOURCE_ID |
constant | Describe / config id for this store (graphicaudio). |
guest::guest_fetch_titleguest::guest_fetch_title_rpcguest::guest_loginguest::guest_login_rpcguest::guest_scan_pageguest::resolve_accessguest::resolve_access_base_urlguest::resolve_bitrateguest::resolve_containerguest::resolve_store_base_url
guest: Guest-process helpers for the external GraphicAudio source plugin.
pub struct GraphicAudioAuthFile {
pub token: String,
pub client_id: String,
pub email: String,
pub marketplace: String,
pub label: Option<String>,
}
Credential envelope for one GraphicAudio 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
token: Opaque device activation token fromPOST activation/login. Empty when the account was logged in with Magento-only access (web/zip).client_id: Device / client id sent at login (stable for this auth file; used bydevice).email: Sign-in email (also the Bookclerk account id).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 for library rows (email).
pub fn has_device_token(&self) -> bool
True when an Access App device token is present.
Implements: Clone, Debug, Deserialize<'de>, Serialize
pub struct MagentoCatalogProduct {
pub product_id: String,
pub sku: Option<String>,
pub title: String,
pub url: Option<String>,
pub series: Option<String>,
pub cover_url: Option<String>,
}
One Magento catalog product (grid / related / product page).
Fields
product_id: Product Identifier.sku: Sku.title: Title.url: URL.series: Series.cover_url: Cover URL.
pub fn is_series_set(&self) -> bool
Is series set.
Implements: Clone, Debug, Eq, PartialEq
pub struct DownloadLinks {
pub lo: Option<String>,
pub hi: Option<String>,
}
Lo/Hi download URLs from api/links.
Fields
lo: Lo.hi: Hi.
pub fn preferred_url(&self) -> Option<&str>
Prefer high-quality URL, else low.
pub fn url_for_quality(&self, prefer_hi: bool) -> Option<&str>
Select Hi or Lo based on whether high quality is preferred.
Implements: Clone, Debug, Deserialize<'de>, Serialize
pub struct GraphicAudioClient {
/* private fields */
}
Authenticated GraphicAudio HTTP helper.
pub fn new(base_url: impl Into<String>) -> Self
Build a client pointed at base_url (trailing slash stripped).
pub fn with_http(self, http: HttpClient) -> Self
Override the HTTP client (tests / custom timeouts).
pub fn with_token(self, token: impl Into<String>) -> Self
Attach an activation token for subsequent requests.
pub fn token(&self) -> Option<&str>
Current token, if any.
pub fn base_url(&self) -> &str
Base URL in use.
pub async fn login(
&mut self,
username: &str,
password: &str,
client_id: &str,
) -> Result<String>
POST activation/login — returns the opaque token string.
Returns an error when the operation fails.
pub async fn products(&self) -> Result<Vec<Product>>
GET api/products — owned titles plus promotional samples.
Returns an error when the operation fails.
pub async fn links(&self, product_id: &str) -> Result<DownloadLinks>
GET api/links?product= — Lo/Hi plain media URLs.
Returns an error when the operation fails.
pub async fn download_to_path(&self, url: &str, path: &Path) -> Result<()>
Stream an absolute media URL to path without buffering the whole
body, resuming a dropped transfer.
Returns an error when the store refuses the file or the transfer keeps failing.
pub async fn remove_activation(&self, client_id: &str) -> Result<()>
POST activation/remove — drop a device slot for client_id.
Returns an error when the operation fails.
Implements: Clone, Debug, Default
pub struct Product {
pub id: String,
pub product_type: Option<String>,
pub product_name: Option<String>,
pub title: Option<String>,
pub author: Option<String>,
pub series: Option<String>,
pub episode: Option<String>,
pub genre: Option<String>,
pub image: Option<String>,
pub thumbnail: Option<String>,
pub running_time: Option<String>,
pub purchased_date: Option<String>,
pub release_date: Option<String>,
}
One library / sample product from api/products.
Fields
id: Identifier.product_type: Product type.product_name: Product name.title: Title.author: Author.series: Series.episode: Episode.genre: Genre.image: Image.thumbnail: Thumbnail.running_time: Running time.purchased_date: Purchased date.release_date: Release date.
pub fn is_sample(&self) -> bool
Whether this entry is a promotional sample (not owned).
pub fn display_title(&self) -> String
Display title preferring Series + ProductName for owned volumes.
Access App owned rows often use a short ProductName (e.g. "Volume 1")
with the work title in Series. Magento downloadable rows use the full
storefront title — combining these fields keeps ZIP matching reliable.
Implements: Clone, Debug, Deserialize<'de>, Serialize
pub struct TitleFetchRequest<'a> {
pub store_base_url: &'a str,
pub email: &'a str,
pub product_id: &'a str,
pub product_title: Option<&'a str>,
pub cache_dir: &'a Path,
pub prefer_hi: bool,
pub mode: GraphicAudioAccess,
pub password: Option<&'a str>,
pub zip_container: GraphicAudioContainer,
}
Parameters for fetch_title_with_mode.
Fields
store_base_url: Store base URL.email: Email.product_id: Product Identifier.product_title: Product title.cache_dir: Absolute path to the download/work cache directory.prefer_hi: Prefer hi.mode: Mode.password: Password.zip_container: ZIP SKU preference whenSelf::modeisGraphicAudioAccess::Zip.
Implements: Clone, Debug
pub struct DownloadableProduct {
pub title: String,
pub option_label: String,
pub download_url: String,
pub remaining: Option<u32>,
pub status: String,
}
One row from My Downloadable Products.
Fields
title: Title.option_label: Option label.download_url: Download URL.remaining: Remaining.status: Status.
pub fn format_rank(&self) -> u8
Rank for Magento ZIP SKU selection (lower = better).
pub fn format_rank_for(&self, preference: GraphicAudioContainer) -> u8
Rank using a configured container preference.
pub fn has_remaining(&self) -> bool
Has remaining.
Implements: Clone, Debug
pub struct LibraryItem {
pub product_id: String,
pub title: Option<String>,
pub listen_path: Option<String>,
}
One owned title from Browser Player content_library HTML.
Fields
product_id: Product Identifier.title: Title.listen_path: Listen path.
Implements: Clone, Debug
pub struct MagentoClient {
/* private fields */
}
Magento customer session + cookie jar (including Browser Player CloudFront cookies).
pub fn new(base_url: impl Into<String>) -> Result<Self>
Build a client for base_url (trailing slash stripped).
Returns an error when the operation fails.
pub fn base_url(&self) -> &str
Base URL.
pub async fn login(&self, email: &str, password: &str) -> Result<()>
Customer login via Magento loginPost (form_key + email/password).
Returns an error when the operation fails.
pub async fn list_downloadable(&self) -> Result<Vec<DownloadableProduct>>
Parse My Downloadable Products into link rows.
Returns an error when the operation fails.
pub async fn resolve_download_url(&self, download_url: &str) -> Result<String>
Resolve a Magento downloadable link to a CDN URL (or stream body if no redirect).
Hitting the Magento /downloadable/download/link/... URL consumes one of the
limited download attempts — callers must finish the transfer.
Returns an error when the operation fails.
pub async fn download_to_path(&self, url: &str, path: &Path) -> Result<()>
Stream url to path, resuming a dropped transfer (uses
Magento/CloudFront cookies when present).
Returns an error when the operation fails.
pub async fn content_library_html(&self) -> Result<String>
Fetch Browser Player library HTML (library/index/content_library).
Returns an error when the operation fails.
pub async fn list_library(&self) -> Result<Vec<LibraryItem>>
List owned titles from Browser Player library (no Access App device token).
Returns an error when the operation fails.
pub async fn player_listen_url(&self, product_id: &str) -> Result<String>
Find Browser Player listen URL for product_id via library/index/content_library.
Returns an error when the operation fails.
pub async fn player_audio_url(&self, product_id: &str) -> Result<String>
Open the Browser Player page and return the <audio> media URL (sets CF cookies).
Returns an error when the operation fails.
Implements: Clone, Debug
pub struct GraphicAudioSource {
/* private fields */
}
GraphicAudio catalog client used by the guest's discovery entrypoints.
The catalog lives on the public Magento storefront, so no account or access path is involved.
pub fn new() -> Self
Production GraphicAudio storefront origin.
pub fn with_store_url(self, store_url: impl Into<String>) -> Self
Override Magento storefront base (wiremock / staging).
pub fn from_config(config: &Value) -> Self
Catalog client for the instance settings document config.
Uses the document's store_url override when it has one, the same
storefront origin crate::guest::resolve_store_base_url gives
sign-in, scans and fetches, so a staging or mock origin reaches every
entrypoint.
pub async fn search_catalog(&self, opts: &CatalogSearchOpts) -> Result<Vec<CatalogHit>>
Searches the public catalog.
The store's search answers a query it cannot match (one with punctuation or an author's name, say) with an alphabetical listing of the whole catalog. So the query goes out as plain words, and an answer that looks like that listing (a full grid, none of it matching the query's words, in alphabetical order) is not taken: the page is asked again with the last word dropped (an author's name usually trails the title), up to three requests in all, and answers nothing when every attempt gets the listing. Each answer is judged by the words sent for it, and a shortened query with no telling words left is not sent. A later page first settles the query on page 1 the same way, then asks for that page with it, and answers nothing when that page looks like the listing. An author or narrator search is sent once and taken as it comes: grid titles never carry a person's name, so the listing check cannot judge it.
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 catalog_detail(&self, product_id: &str) -> Result<Option<CatalogHit>>
The full catalog record of one product, read from its product page.
product_id- The store's numeric product id.
The record, or None when the id is not numeric or the page names
no product.
Returns an error when the page cannot be fetched.
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.
Returns an error when a storefront request or its parse fails and the
method cannot fall back. Failed lookups are soft, so Ok(None) can also
mean the store could not be reached, not only that the title is not sold.
pub async fn purchase_answer(&self, opts: &PurchaseHintOpts) -> Result<PricedAnswer>
Resolves a title's GraphicAudio product and price, with every listing a title search matched.
A known product id, or a host that did not ask for a title search
(lookup other than PriceLookup::Title), gets
Self::purchase_hint's answer. A title search reads the product
page of each of up to TITLE_RECORDS (3) matching results (series sets
left out) once, for its full record (author, cast, ISBN, release
date, running time) and its price, and returns them as priced
records for the host to place. The store's pick is the best title
match.
Returns bookclerk_storefront::SourceError::RateLimited when the
store answers 429. Other failures are soft: a failed search answers
nothing, and a product page that cannot be read leaves that record
lean and unpriced.
Implements: Clone, Debug, Default
pub enum GraphicAudioError {
Auth(String),
NoAccounts(String),
AccountNotFound(String),
Api(String),
Download(String),
Io(Error),
Other(Error),
}
Failures from Magento / Access App auth, library listing, or download.
Variants
Auth: Magento customer login or Access App device activation failed.NoAccounts: No GraphicAudio accounts are configured (safe to skip in multi-source scan).AccountNotFound: Requested account id is not present inencrypted_secrets.Api: Upstream Magento, Access App, or CloudFront API error.Download: Browser-player / ZIP / device 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<Error>, From<GraphicAudioError>
pub enum GraphicAudioAccess {
Web,
Zip,
Device,
}
How GraphicAudio fetches owned audio (the access plugin setting).
Default is Self::Web (Browser Player). ZIP downloads and Access App
device registration are opt-in — do not assume the user purchased a ZIP
SKU or wants a device slot consumed.
Variants
Web: Magento Browser Player (/library) — no ZIP attempts, no device slot.Zip: Magento ZIP download (My Downloadable Products) — ≤3 attempts; opt-in.Device: Access App API (/access) — registers/uses a device activation; opt-in.
pub fn parse(raw: &str) -> Option<Self>
Parse a config / env / CLI token (web, zip, device, plus aliases).
pub fn from_env() -> Option<Self>
Env override BOOKCLERK_GA_ACCESS or legacy BOOKCLERK_GA_FETCH.
Implements: Clone, Copy, Debug, Default, Deserialize<'de>, Eq, PartialEq, Serialize
pub enum GraphicAudioBitrate {
Hi,
Lo,
}
GraphicAudio device encode preference (the bitrate plugin setting).
Variants
Hi: Higher bitrate / Hi URL when available.Lo: Lower bitrate / Lo URL.
pub fn parse(raw: &str) -> Option<Self>
Parse.
pub fn prefers_hi(self) -> bool
Prefers hi.
Implements: Clone, Copy, Debug, Default, Deserialize<'de>, Eq, PartialEq, Serialize
pub enum GraphicAudioContainer {
Auto,
M4b,
Mp3,
Flac,
}
Preferred GraphicAudio ZIP SKU when GraphicAudioAccess::Zip.
Variants
Auto: Prefer M4B, then MP3, then FLAC (default).M4b: M4b variant.Mp3: MP3 variant.Flac: Flac variant.
pub fn parse(raw: &str) -> Option<Self>
Parse.
pub fn format_rank(self, option_label: &str) -> u8
Rank used when sorting Magento downloadable options (lower = better).
Implements: Clone, Copy, Debug, Default, Deserialize<'de>, Eq, PartialEq, Serialize
pub fn catalog_http_client() -> Result<Client>
Shared HTTP client for public Magento catalog pages.
Returns an error when the operation fails.
pub async fn expand_from_product_id(
http: &Client,
store_base: Option<&str>,
product_id: &str,
) -> Result<Vec<MagentoCatalogProduct>>
Expand a owned Magento product id into related + series siblings.
Returns an error when the operation fails.
pub async fn expand_from_search(
http: &Client,
store_base: Option<&str>,
query: &str,
) -> Result<Vec<MagentoCatalogProduct>>
Expand via Magento catalog search (series name or title).
Returns an error when the operation fails.
pub async fn fetch_product_by_id(
http: &Client,
store_base: &str,
product_id: &str,
) -> Result<(String, Vec<MagentoCatalogProduct>, Option<String>)>
Magento product page by numeric product id.
Returns an error when the operation fails.
pub async fn fetch_series_page(
http: &Client,
series_url: &str,
) -> Result<Vec<MagentoCatalogProduct>>
Fetch titles listed on a series category page (includes series-set SKUs).
Returns an error when the operation fails.
pub fn parse_catalog_grid(html: &str) -> Vec<MagentoCatalogProduct>
Parse Magento product grid / related list items.
pub fn parse_related_products(html: &str) -> Vec<MagentoCatalogProduct>
Parse the Recommended / related products block on a product page.
pub async fn search_catalog(
http: &Client,
store_base: &str,
query: &str,
) -> Result<Vec<MagentoCatalogProduct>>
Search Magento catalog; often redirects to a matching series page.
page > 1 tries Magento ?p= once; when that yields nothing the source is
treated as exhausted by the host cursor (empty page).
Returns an error when the operation fails.
pub async fn search_catalog_page(
http: &Client,
store_base: &str,
query: &str,
page: u32,
) -> Result<Vec<MagentoCatalogProduct>>
Like search_catalog with an optional Magento page index.
Returns an error when the operation fails.
pub fn parse_product_detail(html: &str) -> Option<CatalogHit>
Reads one GraphicAudio product page as a catalog record.
html- The product page's HTML, as the store sent it.
The record, or None when the page names no numeric product id or no
title (a search page, an error page, or something else entirely).
pub async fn fetch_title_materials(
client: &GraphicAudioClient,
product_id: &str,
cache_dir: &Path,
) -> Result<PlainFetch>
Password env (same as CLI login) for Magento ZIP / Browser Player.
Fetch one product id into cache_dir via api/links Hi/Lo URLs.
Returns an error when the operation fails.
pub async fn fetch_title_with_mode(
access: &GraphicAudioClient,
req: TitleFetchRequest<'_>,
) -> Result<PlainFetch>
Fetch owned audio for one product using the configured access path only (no ZIP→web→device cascade).
Returns an error when the operation fails.
pub async fn collect_account_books(
auth: &GraphicAudioAuthFile,
access_base: &str,
store_base: &str,
access: GraphicAudioAccess,
magento_password: Option<&str>,
include_samples: bool,
account_id: &str,
marketplace: &str,
) -> Result<(Vec<ScanBook>, u32)>
Collect owned titles for one account (no DB writes).
Prefer Access App catalog when access=device and a device token exists.
For web/zip (default), use Magento Browser Player library so we do not
depend on a device slot for ownership listing. Falls back to Access App
when a legacy device token exists and Magento password is unavailable.
Returns an error when the operation fails.
pub fn product_to_scan_book(
product: &Product,
account_id: &str,
marketplace: &str,
) -> ScanBook
Map a GraphicAudio product JSON object to a structured scan row.
Every GraphicAudio production is a full-cast dramatisation of the work,
so the expression kind is ExpressionKind::Dramatisation.
pub type Result<T> = Result<T, GraphicAudioError>;
Result alias for GraphicAudio auth, sync, and download operations.
pub const DEFAULT_BASE_URL: &str = "https://www.graphicaudio.net/access";
Default API origin (no trailing slash after /access).
pub const LOGIN_PATH: &str = "/activation/login";
Device activation / password login.
pub const PRODUCTS_PATH: &str = "/api/products";
Library + sample products listing.
pub const REMOVE_PATH: &str = "/activation/remove";
Forget a device activation (client_id form field).
pub const GA_ACCESS_ENV: &str = "BOOKCLERK_GA_ACCESS";
Preferred env override (BOOKCLERK_GA_ACCESS); falls back to GA_FETCH_ENV.
pub const GA_FETCH_ENV: &str = "BOOKCLERK_GA_FETCH";
Env override for which GraphicAudio access path to use (legacy name).
pub const DEFAULT_STORE_URL: &str = "https://www.graphicaudio.net";
Default Magento storefront origin (no /access suffix).
pub const GRAPHICAUDIO_SOURCE_ID: &str = "graphicaudio";
Describe / config id for this store (graphicaudio).
Generated from crates/bookclerk-plugins/optional/source-graphicaudio at main · View as Markdown