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.3", 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§
Structs§
- Account
Info - 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.
- AppStore
Product - 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;StoreKitsupplies the name and price. - Auth
Client - 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_urlto the user and obtaining the resultingcodehowever fits its own UI. - Billing
Status - What the account can spend and what it pays for, from
GET /api/billing. - Billing
Subscription - Braille
Table - A
(display_name, table_id)pair fromGET /api/settings/braille_tables. - Created
Document - Response body of
POST /api/documents. - Dialect
- A
(display_name, locale)pair fromGET /api/settings/dialects. - Document
Channel - A live connection to a document’s real-time channel, joined via
crate::ScribeClient::open_document_channel. - Document
List - The result of
GET /api/documents. - Document
Summary - 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 fromGET /api/settings/languages. - Notification
Settings - 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. - Output
List - The result of
GET /api/documents/:id/outputs. - Pkce
Challenge - A generated PKCE (RFC 7636) verifier/challenge pair. Always uses the
S256challenge method; there’s no reason for a client we control to useplain, even though the server supports it. - Scribe
Client - Settings
- A document’s current conversion settings
- Settings
Update - A partial update to a document’s conversion settings
- Token
Set - An access/refresh token pair returned by
POST /oauth/token. - Trashed
Document - One row from
GET /api/documents/trash. - Url
- A parsed URL record.
- Voice
- A
(display_name, voice_short_name, has_sample)triple fromGET /api/settings/voices.
Enums§
- Channel
Event - An event pushed asynchronously over a
DocumentChannel, outside of a direct reply to something we sent. - Document
Source - What to create a document from.
- Output
Format - A document conversion output format.
- Scribe
Error - 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 ofreqwest/serde_jsonhere; those stay out ofDisplay(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 aTokenSetand refreshes it automatically as needed, so construct oneAuthClient/ScribeClientpair 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.