Skip to main content

Crate scribe_client

Crate scribe_client 

Source
Expand description

§scribe-client

A Rust client for the Scribe for Documents API by Pneuma Solutions, which converts documents into accessible formats: HTML, DAISY, EPUB, MP3 audio, and Braille.

It covers signing in (OAuth 2.0 with PKCE), uploading documents, converting them, following a conversion live over a WebSocket channel, downloading the results, and the account and settings around them. The scribe-client Python package is built on it.

§Example

use scribe_client::{reqwest, AuthClient, PkceChallenge, ScribeClient, Url};

#[tokio::main]
async fn main() -> Result<(), scribe_client::ScribeError> {
    let base_url: Url = "https://scribeit.io".parse().expect("a valid URL");
    let client_id = "your-client-id";
    let redirect_uri = "myapp://callback";
    let http = reqwest::Client::new();
    let auth = AuthClient::new(http.clone(), base_url.clone(), client_id);

    // Send the user's browser to this URL. Once they sign in, the server
    // redirects to `redirect_uri` with a `code` query parameter.
    let pkce = PkceChallenge::generate();
    println!("{}", auth.authorization_url(redirect_uri, &pkce));
    let code = "the code from the redirect";

    // Exchange the code for tokens, which `ScribeClient` then refreshes as
    // needed.
    let tokens = auth.exchange_code(redirect_uri, code, pkce.verifier()).await?;
    let client = ScribeClient::new(http, base_url, client_id, tokens);

    for document in client.list_documents().await?.documents {
        println!("{}: {}", document.id, document.title.as_deref().unwrap_or("(untitled)"));
    }
    Ok(())
}

ScribeClient and AuthClient take a reqwest::Client and a Url; use the scribe_client::reqwest and scribe_client::Url re-exports so the versions match.

§TLS

By default TLS is done by rustls, with no system library to link against. To use the platform’s own TLS library instead (Security.framework on Apple platforms, SChannel on Windows, OpenSSL elsewhere), turn off the default features and turn on native-tls:

scribe-client = { version = "0.2", default-features = false, features = ["native-tls"] }

§License

Licensed under either of the Apache License, Version 2.0 or the MIT license, at your option.

Re-exports§

pub use reqwest;
pub use url;

Structs§

AccountInfo
The authenticated user’s name, email, phone number, and (if the account belongs to a real organization rather than an individual) organization name, for read-only display in the app’s Account screen.
AppStoreProduct
A product on sale in the App Store, from GET /api/app_store/products. The server decides what is on sale, so a special can be offered without a new app; StoreKit supplies the name and price.
AuthClient
Drives the OAuth 2.0 Authorization Code + PKCE flow against a Scribe server. This type does not open a browser or run a redirect listener; the embedding application is responsible for presenting AuthClient::authorization_url to the user and obtaining the resulting code however fits its own UI.
BillingStatus
What the account can spend and what it pays for, from GET /api/billing.
BillingSubscription
BrailleTable
A (display_name, table_id) pair from GET /api/settings/braille_tables.
CreatedDocument
Response body of POST /api/documents.
Dialect
A (display_name, locale) pair from GET /api/settings/dialects.
DocumentChannel
A live connection to a document’s real-time channel, joined via crate::ScribeClient::open_document_channel.
DocumentList
The result of GET /api/documents.
DocumentSummary
One row from GET /api/documents.
Download
A downloaded output, with the name the server says to save it under.
Language
A (display_name, language_code) pair from GET /api/settings/languages.
NotificationSettings
A user’s push-notification preference. One flag today, on purpose — device tokens are per-device, so this is user-scoped, not per-document.
Output
One row from GET /api/documents/:id/outputs.
OutputList
The result of GET /api/documents/:id/outputs.
PkceChallenge
A generated PKCE (RFC 7636) verifier/challenge pair. Always uses the S256 challenge method; there’s no reason for a client we control to use plain, even though the server supports it.
ScribeClient
Settings
A document’s current conversion settings
SettingsUpdate
A partial update to a document’s conversion settings
TokenSet
An access/refresh token pair returned by POST /oauth/token.
TrashedDocument
One row from GET /api/documents/trash.
Url
A parsed URL record.
Voice
A (display_name, voice_short_name, has_sample) triple from GET /api/settings/voices.

Enums§

ChannelEvent
An event pushed asynchronously over a DocumentChannel, outside of a direct reply to something we sent.
DocumentSource
What to create a document from.
OutputFormat
A document conversion output format.
ScribeError
Every variant that can originate from a server response carries a message: String — the server’s own human-readable sentence, passed through unchanged. Never build user-facing text from a status code, error code, or the internals of reqwest/serde_json here; those stay out of Display (available via .source() for logging only).
Stage
The current stage of a document conversion.

Constants§

DELETE_ACCOUNT_PATH
A client for the document-conversion endpoints (/api/documents*). Holds a TokenSet and refreshes it automatically as needed, so construct one AuthClient/ScribeClient pair per authenticated user session and reuse it across requests. Path of the web page where a user requests, or cancels, deletion of their own account.