api2convert 10.2.0

Official Rust SDK for the API2Convert file-conversion API — one-call convert with upload, polling, download and webhook verification.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127

//! Extra controls for [`convert`](crate::Api2Convert::convert_with) /
//! [`convert_async`](crate::Api2Convert::convert_async_with).
//!
//! These named controls are kept **strictly separate** from the open-ended
//! conversion-options map, so an API option key can never collide with an SDK
//! control key — a contract requirement.

use std::time::Duration;

use serde_json::{Map, Value};

/// Controls for a synchronous [`convert`](crate::Api2Convert::convert_with).
#[derive(Default, Clone)]
pub struct ConvertOptions {
    pub(crate) conversion_options: Map<String, Value>,
    pub(crate) category: Option<String>,
    pub(crate) filename: Option<String>,
    pub(crate) download_password: Option<String>,
    pub(crate) output_index: usize,
    pub(crate) timeout: Option<Duration>,
}

impl ConvertOptions {
    pub fn new() -> Self {
        Self::default()
    }

    /// Set the whole target-specific conversion-options map (passed 1:1 to the
    /// API's conversion `options`). Discover valid keys via
    /// [`Api2Convert::options`](crate::Api2Convert::options).
    pub fn conversion_options(mut self, options: Map<String, Value>) -> Self {
        self.conversion_options = options;
        self
    }

    /// Add or replace a single conversion option.
    pub fn option(mut self, key: impl Into<String>, value: impl Into<Value>) -> Self {
        self.conversion_options.insert(key.into(), value.into());
        self
    }

    /// Disambiguate an ambiguous target format.
    pub fn category(mut self, category: impl Into<String>) -> Self {
        self.category = Some(category.into());
        self
    }

    /// The advertised filename for an uploaded local file / stream.
    pub fn filename(mut self, filename: impl Into<String>) -> Self {
        self.filename = Some(filename.into());
        self
    }

    /// Protect every output with a download password. It is remembered on the
    /// returned result and sent automatically on download.
    pub fn download_password(mut self, password: impl Into<String>) -> Self {
        self.download_password = Some(password.into());
        self
    }

    /// Which output file the result selects (default `0`).
    pub fn output_index(mut self, index: usize) -> Self {
        self.output_index = index;
        self
    }

    /// Override the poll timeout for this conversion.
    pub fn timeout(mut self, d: Duration) -> Self {
        self.timeout = Some(d);
        self
    }
}

/// Controls for an asynchronous
/// [`convert_async`](crate::Api2Convert::convert_async_with).
#[derive(Default, Clone)]
pub struct AsyncOptions {
    pub(crate) conversion_options: Map<String, Value>,
    pub(crate) category: Option<String>,
    pub(crate) filename: Option<String>,
    pub(crate) download_password: Option<String>,
    pub(crate) callback: Option<String>,
}

impl AsyncOptions {
    pub fn new() -> Self {
        Self::default()
    }

    /// Set the whole target-specific conversion-options map.
    pub fn conversion_options(mut self, options: Map<String, Value>) -> Self {
        self.conversion_options = options;
        self
    }

    /// Add or replace a single conversion option.
    pub fn option(mut self, key: impl Into<String>, value: impl Into<Value>) -> Self {
        self.conversion_options.insert(key.into(), value.into());
        self
    }

    /// Disambiguate an ambiguous target format.
    pub fn category(mut self, category: impl Into<String>) -> Self {
        self.category = Some(category.into());
        self
    }

    /// The advertised filename for an uploaded local file / stream.
    pub fn filename(mut self, filename: impl Into<String>) -> Self {
        self.filename = Some(filename.into());
        self
    }

    /// Protect every output with a download password (sets the job's
    /// `download_passwords`). A later download must supply it, since the
    /// returned [`Job`](crate::Job) is not a result wrapper.
    pub fn download_password(mut self, password: impl Into<String>) -> Self {
        self.download_password = Some(password.into());
        self
    }

    /// A webhook URL to notify on status change (sets `notify_status: true`).
    pub fn callback(mut self, url: impl Into<String>) -> Self {
        self.callback = Some(url.into());
        self
    }
}