Skip to main content

scribe_client/
model.rs

1use std::collections::HashMap;
2
3use serde::{Deserialize, Serialize};
4
5/// A document conversion output format.
6#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
7#[serde(rename_all = "snake_case")]
8pub enum OutputFormat {
9    Html,
10    Pdf,
11    Epub,
12    Daisy,
13    Docx,
14    Brf,
15    Mp3,
16    OfflineHtml,
17    Mobi,
18    HtmlStream,
19}
20
21impl OutputFormat {
22    #[must_use]
23    pub fn as_str(&self) -> &'static str {
24        match self {
25            OutputFormat::Html => "html",
26            OutputFormat::Pdf => "pdf",
27            OutputFormat::Epub => "epub",
28            OutputFormat::Daisy => "daisy",
29            OutputFormat::Docx => "docx",
30            OutputFormat::Brf => "brf",
31            OutputFormat::Mp3 => "mp3",
32            OutputFormat::OfflineHtml => "offline_html",
33            OutputFormat::Mobi => "mobi",
34            OutputFormat::HtmlStream => "html_stream",
35        }
36    }
37
38    #[must_use]
39    pub fn parse(s: &str) -> Option<Self> {
40        Some(match s {
41            "html" => OutputFormat::Html,
42            "pdf" => OutputFormat::Pdf,
43            "epub" => OutputFormat::Epub,
44            "daisy" => OutputFormat::Daisy,
45            "docx" => OutputFormat::Docx,
46            "brf" => OutputFormat::Brf,
47            "mp3" => OutputFormat::Mp3,
48            "offline_html" => OutputFormat::OfflineHtml,
49            "mobi" => OutputFormat::Mobi,
50            "html_stream" => OutputFormat::HtmlStream,
51            _ => return None,
52        })
53    }
54}
55
56/// The current stage of a document conversion.
57#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
58#[serde(rename_all = "snake_case")]
59pub enum Stage {
60    Queue,
61    Start,
62    Convert,
63    AddImageDescriptions,
64    Complete,
65}
66
67impl Stage {
68    #[must_use]
69    pub fn is_complete(&self) -> bool {
70        matches!(self, Stage::Complete)
71    }
72
73    #[must_use]
74    pub fn as_str(&self) -> &'static str {
75        match self {
76            Stage::Queue => "queue",
77            Stage::Start => "start",
78            Stage::Convert => "convert",
79            Stage::AddImageDescriptions => "add_image_descriptions",
80            Stage::Complete => "complete",
81        }
82    }
83}
84
85/// One row from `GET /api/documents/:id/outputs`.
86#[derive(Debug, Clone, Deserialize)]
87pub struct Output {
88    pub format: OutputFormat,
89    pub stage: Stage,
90    pub progress: f64,
91    pub estimated_time_remaining: Option<i64>,
92    pub is_preview: bool,
93    /// Whether the server offers this output as a download. The in-app HTML
94    /// preview formats are not. Defaults to true for a server that predates
95    /// the field.
96    #[serde(default = "default_true")]
97    pub downloadable: bool,
98}
99
100fn default_true() -> bool {
101    true
102}
103
104/// A downloaded output, with the name the server says to save it under.
105#[derive(Debug, Clone)]
106pub struct Download {
107    pub data: Vec<u8>,
108    /// From the response's `Content-Disposition`, or `None` if it had no
109    /// usable file name.
110    pub file_name: Option<String>,
111}
112
113/// Response body of `POST /api/documents`.
114#[derive(Debug, Clone, Deserialize)]
115pub struct CreatedDocument {
116    pub document_id: String,
117}
118
119/// The result of `GET /api/documents/:id/outputs`.
120#[derive(Debug, Clone, Deserialize)]
121pub struct OutputList {
122    pub outputs: Vec<Output>,
123    /// The document is a password-protected file that hasn't been unlocked
124    /// yet. It has no outputs at all while this is true, so an empty
125    /// `outputs` alone doesn't distinguish "locked" from "not started".
126    #[serde(default)]
127    pub is_password_needed: bool,
128}
129
130#[derive(Debug, Deserialize)]
131pub(crate) struct OutputListResponse {
132    pub outputs: Vec<Output>,
133    #[serde(default)]
134    pub is_password_needed: bool,
135}
136
137/// One row from `GET /api/documents`.
138#[derive(Debug, Clone, Deserialize)]
139pub struct DocumentSummary {
140    pub id: String,
141    /// `None` if the document hasn't been titled yet (e.g. a URL-sourced
142    /// document before the converter has determined one).
143    pub title: Option<String>,
144    pub page_count: Option<i64>,
145    /// ISO 8601 UTC timestamp of when the document was created.
146    pub inserted_at: String,
147    /// The document is a password-protected file that hasn't been unlocked
148    /// yet, so it has no outputs and nothing can be downloaded from it.
149    #[serde(default)]
150    pub is_password_needed: bool,
151    pub outputs: Vec<Output>,
152}
153
154/// The result of `GET /api/documents`.
155#[derive(Debug, Clone, Deserialize)]
156pub struct DocumentList {
157    pub documents: Vec<DocumentSummary>,
158    pub pages_remaining: Option<i64>,
159}
160
161#[derive(Debug, Deserialize)]
162pub(crate) struct DocumentListResponse {
163    pub documents: Vec<DocumentSummary>,
164    pub pages_remaining: Option<i64>,
165}
166
167/// One row from `GET /api/documents/trash`.
168#[derive(Debug, Clone, Deserialize)]
169pub struct TrashedDocument {
170    pub id: String,
171    pub title: Option<String>,
172    pub page_count: Option<i64>,
173    /// ISO 8601 UTC timestamp of when the document was created.
174    pub inserted_at: String,
175    /// ISO 8601 UTC timestamp of when the document was moved to the trash.
176    pub trashed_at: String,
177    /// ISO 8601 UTC timestamp of when the document will be permanently
178    /// deleted if it isn't recovered first.
179    pub permanently_delete_at: String,
180}
181
182#[derive(Debug, Deserialize)]
183pub(crate) struct TrashedDocumentListResponse {
184    pub documents: Vec<TrashedDocument>,
185}
186
187/// A document's current conversion settings
188#[allow(clippy::struct_excessive_bools)] // mirrors the server's flat settings shape
189#[derive(Debug, Clone, Deserialize)]
190pub struct Settings {
191    pub language: Option<String>,
192    pub dialects: serde_json::Value,
193    pub voices: serde_json::Value,
194    pub tts_gender: Option<String>,
195    pub tts_rate: f64,
196    pub braille_translation_table: String,
197    pub braille_cells_per_line: i64,
198    pub braille_split_into_pages: bool,
199    pub braille_lines_per_page: i64,
200    pub large_print: bool,
201    pub add_image_descriptions: bool,
202    pub math: bool,
203    pub notify_when_complete: bool,
204}
205
206/// A partial update to a document's conversion settings
207#[derive(Debug, Clone, Default, Serialize, Deserialize)]
208pub struct SettingsUpdate {
209    #[serde(default, skip_serializing_if = "Option::is_none")]
210    pub language: Option<String>,
211    #[serde(default, skip_serializing_if = "Option::is_none")]
212    pub dialects: Option<serde_json::Value>,
213    #[serde(default, skip_serializing_if = "Option::is_none")]
214    pub voices: Option<serde_json::Value>,
215    #[serde(default, skip_serializing_if = "Option::is_none")]
216    pub tts_gender: Option<String>,
217    #[serde(default, skip_serializing_if = "Option::is_none")]
218    pub tts_rate: Option<f64>,
219    #[serde(default, skip_serializing_if = "Option::is_none")]
220    pub braille_translation_table: Option<String>,
221    #[serde(default, skip_serializing_if = "Option::is_none")]
222    pub braille_cells_per_line: Option<i64>,
223    #[serde(default, skip_serializing_if = "Option::is_none")]
224    pub braille_split_into_pages: Option<bool>,
225    #[serde(default, skip_serializing_if = "Option::is_none")]
226    pub braille_lines_per_page: Option<i64>,
227    #[serde(default, skip_serializing_if = "Option::is_none")]
228    pub large_print: Option<bool>,
229    #[serde(default, skip_serializing_if = "Option::is_none")]
230    pub add_image_descriptions: Option<bool>,
231    #[serde(default, skip_serializing_if = "Option::is_none")]
232    pub math: Option<bool>,
233    #[serde(default, skip_serializing_if = "Option::is_none")]
234    pub notify_when_complete: Option<bool>,
235}
236
237/// A user's push-notification preference. One flag today, on purpose —
238/// device tokens are per-device, so this is user-scoped, not per-document.
239#[derive(Debug, Clone, Serialize, Deserialize)]
240pub struct NotificationSettings {
241    pub push_notify_when_complete: bool,
242}
243
244/// The authenticated user's name, email, phone number, and (if the account
245/// belongs to a real organization rather than an individual) organization
246/// name, for read-only display in the app's Account screen.
247#[derive(Debug, Clone, Serialize, Deserialize)]
248pub struct AccountInfo {
249    pub first_name: Option<String>,
250    pub last_name: Option<String>,
251    pub email: Option<String>,
252    pub phone_number: Option<String>,
253    pub organization_name: Option<String>,
254}
255
256/// A `(display_name, language_code)` pair from `GET /api/settings/languages`.
257#[derive(Debug, Clone, Deserialize)]
258pub struct Language(pub String, pub String);
259
260/// A `(display_name, locale)` pair from `GET /api/settings/dialects`.
261#[derive(Debug, Clone, Deserialize)]
262pub struct Dialect(pub String, pub String);
263
264/// A `(display_name, table_id)` pair from `GET /api/settings/braille_tables`.
265#[derive(Debug, Clone, Deserialize)]
266pub struct BrailleTable(pub String, pub String);
267
268/// A `(display_name, voice_short_name, has_sample)` triple from
269/// `GET /api/settings/voices`.
270#[derive(Debug, Clone, Deserialize)]
271pub struct Voice(pub String, pub String, pub bool);
272
273#[derive(Debug, Deserialize)]
274pub(crate) struct LanguagesResponse {
275    pub languages: Vec<Language>,
276}
277
278#[derive(Debug, Deserialize)]
279pub(crate) struct DialectsResponse {
280    pub dialects: HashMap<String, Vec<Dialect>>,
281}
282
283#[derive(Debug, Deserialize)]
284pub(crate) struct BrailleTablesResponse {
285    pub braille_tables: Vec<BrailleTable>,
286}
287
288#[derive(Debug, Deserialize)]
289pub(crate) struct VoicesResponse {
290    pub voices: HashMap<String, Vec<Voice>>,
291}
292
293#[cfg(test)]
294mod tests {
295    use super::*;
296
297    #[test]
298    fn output_format_as_str_and_parse_round_trip() {
299        let all = [
300            OutputFormat::Html,
301            OutputFormat::Pdf,
302            OutputFormat::Epub,
303            OutputFormat::Daisy,
304            OutputFormat::Docx,
305            OutputFormat::Brf,
306            OutputFormat::Mp3,
307            OutputFormat::OfflineHtml,
308            OutputFormat::Mobi,
309            OutputFormat::HtmlStream,
310        ];
311        for format in all {
312            assert_eq!(OutputFormat::parse(format.as_str()), Some(format));
313        }
314        assert_eq!(OutputFormat::parse("not_a_format"), None);
315    }
316
317    #[test]
318    fn only_the_complete_stage_reports_is_complete() {
319        let all = [
320            Stage::Queue,
321            Stage::Start,
322            Stage::Convert,
323            Stage::AddImageDescriptions,
324            Stage::Complete,
325        ];
326        for stage in all {
327            assert_eq!(stage.is_complete(), stage == Stage::Complete);
328        }
329    }
330
331    #[test]
332    fn stage_as_str_round_trips_through_json() {
333        let all = [
334            (Stage::Queue, "queue"),
335            (Stage::Start, "start"),
336            (Stage::Convert, "convert"),
337            (Stage::AddImageDescriptions, "add_image_descriptions"),
338            (Stage::Complete, "complete"),
339        ];
340        for (stage, expected) in all {
341            assert_eq!(stage.as_str(), expected);
342            let deserialized: Stage = serde_json::from_str(&format!("{expected:?}")).unwrap();
343            assert_eq!(deserialized, stage);
344        }
345    }
346}