pub struct ScribeClient { /* private fields */ }Implementations§
Source§impl ScribeClient
impl ScribeClient
pub fn new( http: Client, base_url: Url, client_id: impl Into<String>, tokens: TokenSet, ) -> Self
Sourcepub async fn current_tokens(&self) -> TokenSet
pub async fn current_tokens(&self) -> TokenSet
Returns a snapshot of the current token set. Useful for persisting the session after the client has auto-refreshed it.
Sourcepub async fn create_document(
&self,
source: DocumentSource,
password: Option<&str>,
) -> Result<CreatedDocument, ScribeError>
pub async fn create_document( &self, source: DocumentSource, password: Option<&str>, ) -> Result<CreatedDocument, ScribeError>
Creates a document from source.
§Errors
Returns ScribeError::Http/ScribeError::Api if the request
fails or the server rejects it.
password unlocks a password-protected source file. Supplying it up
front saves a round trip when the caller already knows the document
is protected; otherwise leave it None and handle the
password_required signal on the document channel.
Sourcepub async fn list_documents(&self) -> Result<DocumentList, ScribeError>
pub async fn list_documents(&self) -> Result<DocumentList, ScribeError>
Lists every document owned by the current user, each with its
outputs embedded (so this alone is enough to show a document list
with per-document conversion status, no follow-up list_outputs
calls needed).
§Errors
Returns ScribeError::Http/ScribeError::Api on request failure.
Sourcepub async fn trash_document(&self, document_id: &str) -> Result<(), ScribeError>
pub async fn trash_document(&self, document_id: &str) -> Result<(), ScribeError>
Moves a document to the trash. It’s permanently deleted 7 days later,
or sooner per the owner’s org retention policy, unless recovered
first with recover_document.
§Errors
Returns ScribeError::NotFound/ScribeError::Forbidden if the
document doesn’t exist or isn’t owned by the caller, or
ScribeError::Http/ScribeError::Api on other request failures.
Sourcepub async fn delete_document_permanently(
&self,
document_id: &str,
) -> Result<(), ScribeError>
pub async fn delete_document_permanently( &self, document_id: &str, ) -> Result<(), ScribeError>
Permanently deletes a document and all of its outputs. The document
must already be in the trash (see
trash_document).
§Errors
Returns ScribeError::NotFound/ScribeError::Forbidden if the
document doesn’t exist or isn’t owned by the caller,
ScribeError::NotTrashed if it hasn’t been moved to the trash yet,
or ScribeError::Http/ScribeError::Api on other request
failures.
Sourcepub async fn recover_document(
&self,
document_id: &str,
) -> Result<(), ScribeError>
pub async fn recover_document( &self, document_id: &str, ) -> Result<(), ScribeError>
Restores a trashed document, clearing its trash state.
§Errors
Returns ScribeError::NotFound/ScribeError::Forbidden if the
document doesn’t exist or isn’t owned by the caller, or
ScribeError::Http/ScribeError::Api on other request failures.
Sourcepub async fn list_trashed_documents(
&self,
) -> Result<Vec<TrashedDocument>, ScribeError>
pub async fn list_trashed_documents( &self, ) -> Result<Vec<TrashedDocument>, ScribeError>
Lists the caller’s trashed documents, most recently trashed first.
§Errors
Returns ScribeError::Http/ScribeError::Api on request failure.
Sourcepub async fn submit_document_feedback(
&self,
document_id: &str,
comment: &str,
) -> Result<(), ScribeError>
pub async fn submit_document_feedback( &self, document_id: &str, comment: &str, ) -> Result<(), ScribeError>
Submits a document for human review, attaching comment as the
reason / description of the problem.
Sourcepub async fn open_document_channel(
&self,
document_id: &str,
) -> Result<DocumentChannel, ScribeError>
pub async fn open_document_channel( &self, document_id: &str, ) -> Result<DocumentChannel, ScribeError>
Opens a real-time channel for document_id, subscribing to
progress on whatever formats are already in progress (or their
incomplete parent formats) and allowing new conversions to be
started with DocumentChannel::start_conversion. This is the
only way to start a conversion for a format other than the
html_stream preview create_document already starts — it’s no
longer possible over plain REST, so the server can guarantee it’s
subscribed to whatever it just started converting.
§Errors
Returns ScribeError::NotFound/ScribeError::Forbidden if the
document doesn’t exist or isn’t owned by the caller, or
ScribeError::WebSocket if the connection fails.
Sourcepub async fn list_outputs(
&self,
document_id: &str,
) -> Result<OutputList, ScribeError>
pub async fn list_outputs( &self, document_id: &str, ) -> Result<OutputList, ScribeError>
§Errors
Returns ScribeError::NotFound/ScribeError::Forbidden if the
document doesn’t exist or isn’t owned by the caller, or
ScribeError::Http/ScribeError::Api on other request failures.
Sourcepub async fn download_output(
&self,
document_id: &str,
format: OutputFormat,
) -> Result<Download, ScribeError>
pub async fn download_output( &self, document_id: &str, format: OutputFormat, ) -> Result<Download, ScribeError>
§Errors
Returns ScribeError::ConversionNotComplete if that format hasn’t
finished converting yet, ScribeError::NotFound/ScribeError::Forbidden
if the document doesn’t exist or isn’t owned by the caller, or
ScribeError::Http/ScribeError::Api on other request failures.
Sourcepub async fn download_url(
&self,
document_id: &str,
format: OutputFormat,
) -> Result<Option<String>, ScribeError>
pub async fn download_url( &self, document_id: &str, format: OutputFormat, ) -> Result<Option<String>, ScribeError>
Where the file can be fetched from directly, when the server answers with a redirect rather than the bytes.
The API redirects to storage by default, and that URL carries a real
Content-Length and accepts range requests, which is what a media
player needs to start before the whole file has arrived and to seek
afterwards. None means this server sends the file itself, so the
caller has to download it first.
§Errors
The same as download_output.
Sourcepub async fn download_output_with_progress<F>(
&self,
document_id: &str,
format: OutputFormat,
on_progress: F,
) -> Result<Download, ScribeError>
pub async fn download_output_with_progress<F>( &self, document_id: &str, format: OutputFormat, on_progress: F, ) -> Result<Download, ScribeError>
As download_output, reporting bytes received
as they arrive: (downloaded, total), where total is None when the
server doesn’t say how big the file is.
Audio of a long document is tens of megabytes, and the whole download used to be one silent wait.
§Errors
The same as download_output.
Sourcepub async fn get_settings(
&self,
document_id: &str,
) -> Result<Settings, ScribeError>
pub async fn get_settings( &self, document_id: &str, ) -> Result<Settings, ScribeError>
§Errors
Returns ScribeError::NotFound/ScribeError::Forbidden if the
document doesn’t exist or isn’t owned by the caller, or
ScribeError::Http/ScribeError::Api on other request failures.
Sourcepub async fn update_settings(
&self,
document_id: &str,
update: &SettingsUpdate,
) -> Result<Settings, ScribeError>
pub async fn update_settings( &self, document_id: &str, update: &SettingsUpdate, ) -> Result<Settings, ScribeError>
§Errors
Returns ScribeError::NotFound/ScribeError::Forbidden if the
document doesn’t exist or isn’t owned by the caller, or
ScribeError::Http/ScribeError::Api on other request failures
(including validation errors on the settings themselves).
Sourcepub async fn rename_document(
&self,
document_id: &str,
title: &str,
) -> Result<DocumentSummary, ScribeError>
pub async fn rename_document( &self, document_id: &str, title: &str, ) -> Result<DocumentSummary, ScribeError>
Changes a document’s title.
Titles start life as the uploaded file name, which for a photo or a share-sheet import is something like “IMG_6746783276432”, so this is how a caller fixes one after the fact. Returns the document as the list endpoint describes it, so a caller can refresh its row from the result.
§Errors
Returns ScribeError::NotFound/ScribeError::Forbidden if the
document doesn’t exist or isn’t owned by the caller, or
ScribeError::Api if the title is rejected (it may not be blank and
is capped at 255 characters).
Sourcepub async fn browser_entry_url(
&self,
return_to_path: &str,
) -> Result<String, ScribeError>
pub async fn browser_entry_url( &self, return_to_path: &str, ) -> Result<String, ScribeError>
A URL that signs the system browser in as this client’s user, then lands
on return_to_path.
The app and the browser do not share a session, so a bare link to a
settings page would greet the user with a login form. This hands the
app’s access token to /auth/browser_from_oauth, which trades it for a
browser session and redirects.
Refreshes the token first when it is near expiry. The server rejects a stale one with a “Failed to log in” page, and that is the page the user would land on.
§Errors
Returns ScribeError::InvalidGrant if the token has expired and cannot
be refreshed, or ScribeError::Http if the refresh request fails.
Sourcepub async fn delete_account_url(&self) -> Result<String, ScribeError>
pub async fn delete_account_url(&self) -> Result<String, ScribeError>
The account-deletion page, signed in, for an app that lets users start deleting their account from inside it.
§Errors
As for ScribeClient::browser_entry_url.
Sourcepub async fn default_settings(&self) -> Result<Settings, ScribeError>
pub async fn default_settings(&self) -> Result<Settings, ScribeError>
The caller’s default conversion settings, which every new document’s settings are seeded from.
Account-scoped, so there is no id: a user has exactly one set, and the server creates it on first read rather than returning a 404.
§Errors
Returns ScribeError::Http/ScribeError::Api on request failure.
Sourcepub async fn update_default_settings(
&self,
update: &SettingsUpdate,
) -> Result<Settings, ScribeError>
pub async fn update_default_settings( &self, update: &SettingsUpdate, ) -> Result<Settings, ScribeError>
Updates the caller’s default conversion settings. Partial: fields left
None on update are not sent, so they keep their current value.
Changing these does not touch documents that already exist.
§Errors
Returns ScribeError::Http/ScribeError::Api on request failure,
including validation errors on the settings themselves.
Sourcepub async fn register_device(
&self,
token: &str,
platform: &str,
) -> Result<(), ScribeError>
pub async fn register_device( &self, token: &str, platform: &str, ) -> Result<(), ScribeError>
Registers token (the hex-encoded APNs device token) so the server
can send this device push notifications. Registration is an upsert —
re-registering the same token re-points it at the current user (e.g.
after signing out and into a different account on the same device).
§Errors
Returns ScribeError::Http/ScribeError::Api on request failure.
Sourcepub async fn unregister_device(&self, token: &str) -> Result<(), ScribeError>
pub async fn unregister_device(&self, token: &str) -> Result<(), ScribeError>
Unregisters token, e.g. on sign-out, so this device stops receiving push.
§Errors
Returns ScribeError::Http/ScribeError::Api on request failure.
Sourcepub async fn get_notification_settings(
&self,
) -> Result<NotificationSettings, ScribeError>
pub async fn get_notification_settings( &self, ) -> Result<NotificationSettings, ScribeError>
§Errors
Returns ScribeError::Http/ScribeError::Api on request failure.
Sourcepub async fn update_notification_settings(
&self,
push_notify_when_complete: bool,
) -> Result<NotificationSettings, ScribeError>
pub async fn update_notification_settings( &self, push_notify_when_complete: bool, ) -> Result<NotificationSettings, ScribeError>
§Errors
Returns ScribeError::Http/ScribeError::Api on request failure.
Sourcepub async fn get_account_info(&self) -> Result<AccountInfo, ScribeError>
pub async fn get_account_info(&self) -> Result<AccountInfo, ScribeError>
§Errors
Returns ScribeError::Http/ScribeError::Api on request failure.
Sourcepub async fn languages(&self) -> Result<Vec<Language>, ScribeError>
pub async fn languages(&self) -> Result<Vec<Language>, ScribeError>
§Errors
Returns ScribeError::Http/ScribeError::Api on request failure.
Sourcepub async fn dialects(
&self,
) -> Result<HashMap<String, Vec<Dialect>>, ScribeError>
pub async fn dialects( &self, ) -> Result<HashMap<String, Vec<Dialect>>, ScribeError>
§Errors
Returns ScribeError::Http/ScribeError::Api on request failure.
Sourcepub async fn braille_tables(&self) -> Result<Vec<BrailleTable>, ScribeError>
pub async fn braille_tables(&self) -> Result<Vec<BrailleTable>, ScribeError>
§Errors
Returns ScribeError::Http/ScribeError::Api on request failure.
Sourcepub async fn voices(&self) -> Result<HashMap<String, Vec<Voice>>, ScribeError>
pub async fn voices(&self) -> Result<HashMap<String, Vec<Voice>>, ScribeError>
§Errors
Returns ScribeError::Http/ScribeError::Api on request failure.