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!("The `file_upload` feature is useless on it's own. You also need to enable one of: `async`, `blocking` ");
28
29use bon::Builder;
30
31#[cfg(feature = "async")]
32pub mod api_async;
33
34#[cfg(feature = "blocking")]
35pub mod api_blocking;
36
37// If neither the `async` nor `blocking` features are enabled, then the `auth` module is not needed.
38#[cfg(any(feature = "async", feature = "blocking"))]
39pub mod auth;
40
41mod credentials;
42pub use credentials::Credentials;
43
44#[cfg(feature = "credentials_loader")]
45mod credentials_loader;
46#[cfg(feature = "credentials_loader")]
47pub use credentials_loader::{CredentialProfiles, CredentialsLoaderError};
48
49pub mod operations;
50
51#[cfg(feature = "file_upload")]
52pub mod file_upload;
53
54/// Base path for the remote.it API.
55pub const BASE_URL: &str = "https://api.remote.it";
56
57/// Path for the GraphQL API. Append this to [`BASE_URL`] to get the full URL.
58pub const GRAPHQL_PATH: &str = "/graphql/v1";
59
60/// Path for file uploads. Append this to [`BASE_URL`] to get the full URL.
61pub const FILE_UPLOAD_PATH: &str = "/graphql/v1/file/upload";
62
63/// A client for the remote.it API.
64///
65/// # Example
66/// You can create a new [`R3Client`] using the builder pattern:
67/// ```
68/// # use remoteit_api::R3Client;
69/// # use remoteit_api::Credentials;
70/// let credentials: Credentials = Credentials::load_from_disk()
71///     .custom_credentials_path(".env.remoteit")
72///     .call()
73///     .expect("Couldn't load credentials!")
74///     .take_profile("default")
75///     .expect("Couldn't parse secret access key!")
76///     .expect("Profile with given name does not exist!");
77/// let client = R3Client::builder().credentials(credentials).build();
78/// // Start making API calls
79/// let devices = client.get_devices().call().unwrap();
80/// ```
81#[derive(Builder, Clone, Debug)]
82pub struct R3Client {
83    credentials: Credentials,
84}
85
86impl R3Client {
87    /// # Returns
88    /// A reference to the credentials used by the client.
89    #[must_use]
90    pub fn credentials(&self) -> &Credentials {
91        &self.credentials
92    }
93}
remoteit_api/lib.rs

remoteit_api/
lib.rs
