remoteit_api/
lib.rs

1//! # Remote.it API Wrapper
2//!
3//! The most important structs are [`R3Client`] and [`Credentials`].
4//!
5//! To use this crate obtain your [`Credentials`] by loading them from disk using the provided methods,
6//! or, if you want to store the credentials in another way, instantiate a [`Credentials`] struct directly.
7//! See [`Credentials::load_from_disk`] and [`Credentials::builder`] for details and examples.
8//!
9//! Then instantiate an [`R3Client`] using [`R3Client::builder`] and start calling the API functions on it.
10//!
11//! # Features
12//!
13//! - Enable `blocking` to use the blocking versions of the API functions from the [`api_blocking`] module.
14//! - Enable `async` to use the asynchronous versions of the API funcitons from the [`api_async`] module.
15//! - Enable `credentials_loader` to use the [`Credentials::load_from_disk`] function.
16//!   This is gated behind a feature, because it introduces additional dependencies.
17//!
18
19// Enable all features for the documentation tests
20#![cfg_attr(docsrs, feature(doc_cfg))]
21#![cfg_attr(docsrs, doc(cfg(all())))]
22
23#[cfg(all(
24    feature = "file_upload",
25    not(any(feature = "async", feature = "blocking"))
26))]
27compile_error!(
28    "The `file_upload` feature is useless on it's own. You also need to enable one of: `async`, `blocking` "
29);
30
31use bon::Builder;
32
33#[cfg(feature = "async")]
34pub mod api_async;
35
36#[cfg(feature = "blocking")]
37pub mod api_blocking;
38
39// If neither the `async` nor `blocking` features are enabled, then the `auth` module is not needed.
40#[cfg(any(feature = "async", feature = "blocking"))]
41pub mod auth;
42
43mod credentials;
44pub use credentials::Credentials;
45
46#[cfg(feature = "credentials_loader")]
47mod credentials_loader;
48#[cfg(feature = "credentials_loader")]
49pub use credentials_loader::{CredentialProfiles, CredentialsLoaderError};
50
51pub mod operations;
52
53#[cfg(feature = "file_upload")]
54pub mod file_upload;
55
56/// Base path for the remote.it API.
57pub const BASE_URL: &str = "https://api.remote.it";
58
59/// Path for the GraphQL API. Append this to [`BASE_URL`] to get the full URL.
60pub const GRAPHQL_PATH: &str = "/graphql/v1";
61
62/// Path for file uploads. Append this to [`BASE_URL`] to get the full URL.
63pub const FILE_UPLOAD_PATH: &str = "/graphql/v1/file/upload";
64
65/// A client for the remote.it API.
66///
67/// # Example
68/// You can create a new [`R3Client`] using the builder pattern:
69/// ```
70/// # use remoteit_api::R3Client;
71/// # use remoteit_api::Credentials;
72/// let credentials: Credentials = Credentials::load_from_disk()
73///     .custom_credentials_path(".env.remoteit")
74///     .call()
75///     .expect("Couldn't load credentials!")
76///     .take_profile("default")
77///     .expect("Couldn't parse secret access key!")
78///     .expect("Profile with given name does not exist!");
79/// let client = R3Client::builder().credentials(credentials).build();
80/// // Start making API calls
81/// let devices = client.get_devices().call().unwrap();
82/// ```
83#[derive(Builder, Clone, Debug)]
84pub struct R3Client {
85    credentials: Credentials,
86}
87
88impl R3Client {
89    /// # Returns
90    /// A reference to the credentials used by the client.
91    #[must_use]
92    pub fn credentials(&self) -> &Credentials {
93        &self.credentials
94    }
95}
remoteit_api/lib.rs

remoteit_api/
lib.rs
