bookclerk_plugin_source_chirp::guest

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

Last updated View as Markdown

Guest-process helpers for the external Chirp source plugin.

These APIs do not open the library DB — the host seals credentials and upserts scan rows via bookclerk_plugin_host::ExternalSource. Conversions between storefront types and the typed ABI live in bookclerk_storefront::abi.

Item Kind Summary
guest_login function Login against Chirp and return account metadata + credential JSON.
guest_login_rpc function RPC login: build LoginOptions from typed params and return the ABI result.
guest_scan_page function RPC scan: one page of one account's full pass (the host upserts books).
guest_fetch_title function Download one title into cache_dir using host-injected credentials.
guest_fetch_title_rpc function RPC fetch: return the typed plain fetch result.
resolve_graphql_url function Resolve GraphQL endpoint (tests may override via the plugin settings document).
source_id function Source id returned in describe(); must match crate::source::ID.

Functions

guest_login

pub async fn guest_login(
    graphql_url: &str,
    opts: LoginOptions,
) -> Result<(String, String, Option<String>, bool, Value)>

Login against Chirp and return account metadata + credential JSON.

Does not write to encrypted_secrets — the host seals credentials.

Errors

Returns an error when the operation fails.

guest_login_rpc

pub async fn guest_login_rpc(
    graphql_url: &str,
    params: LoginParams,
) -> Result<LoginResult>

RPC login: build LoginOptions from typed params and return the ABI result.

Errors

Returns an error when the operation fails.

guest_scan_page

pub async fn guest_scan_page(
    graphql_url: &str,
    params: &ScanParams,
    scan_state: Option<&DatabaseBinding>,
) -> Result<ScanPage, PluginError>

RPC scan: one page of one account's full pass (the host upserts books).

Chirp has no delta API, so every pass fetches the whole library. With the SCAN_STATE database, ScanDelta sends the host only titles that are new or changed since the last pass, and the product ids that disappeared; without it every pass is full and ends complete. The SDK's scan_page helper pages the store's numbered library pages into scan replies.

Arguments

  • graphql_url - Chirp GraphQL endpoint.
  • params - The pass's account, credential, page size, cursor and sync token.
  • scan_state - The SCAN_STATE database, when granted.

Errors

Returns invalid_cursor for a cursor or sync token this plugin cannot use, the database's error when scan state cannot be kept, and internal when the credential is missing or invalid or the page request fails.

guest_fetch_title

pub async fn guest_fetch_title(
    graphql_url: &str,
    credentials: &Value,
    title_id: &str,
    cache_dir: &Path,
) -> Result<PlainFetch>

Download one title into cache_dir using host-injected credentials.

Errors

Returns an error when the operation fails.

guest_fetch_title_rpc

pub async fn guest_fetch_title_rpc(
    graphql_url: &str,
    params: &FetchTitleParams,
) -> Result<PlainFetch>

RPC fetch: return the typed plain fetch result.

Errors

Returns an error when the operation fails.

resolve_graphql_url

pub fn resolve_graphql_url(source_config: &Value) -> String

Resolve GraphQL endpoint (tests may override via the plugin settings document).

source_id

pub fn source_id() -> &'static str

Source id returned in describe(); must match crate::source::ID.

Generated from crates/bookclerk-plugins/optional/source-chirp at main · View as Markdown