ring_client/lib.rs
1#![deny(missing_docs)]
2#![deny(clippy::all)]
3#![warn(clippy::pedantic)]
4#![warn(clippy::nursery)]
5#![warn(missing_debug_implementations, rust_2018_idioms, rustdoc::all)]
6#![allow(rustdoc::private_doc_tests)]
7#![forbid(unsafe_code)]
8#![deny(clippy::clone_on_ref_ptr)]
9
10//! # Ring Client
11//!
12//! The Ring Client crate provides a client for interfacing with [Ring](https://www.ring.com/)
13//! home security devices.
14//!
15//! ## Usage
16//! ```toml
17//! [dependencies]
18//! ring-client = "0.0.2"
19//! ```
20//!
21//! ## Capabilities
22//!
23//! 1. Authenticate with Ring - either via Username and Password, or Refresh Tokens.
24//! 2. Interact with Ring locations - including listening for events (such as motion detectors) in
25//! real-time, as well as changing the states of devices (such as enabling or disabling an Alarm system).
26//! 3. Retrieve profile information.
27//!
28//! ## Examples
29//!
30//! More in-depth examples can be found in documentation comments on the Client methods.
31//!
32//! ## Listening for Events
33//!
34//! Perhaps one of the most useful features of the crate is the ability to listen and respond to
35//! events which occur in a location in real-time.
36//!
37//! This is done using the [`crate::location::Location::listen_for_events`] method.
38//!
39//! ```no_run
40//! use ring_client::Client;
41//!
42//! use ring_client::authentication::Credentials;
43//! use ring_client::OperatingSystem;
44//!
45//! # tokio_test::block_on(async {
46//! let client = Client::new("Home Automation", "mock-system-id", OperatingSystem::Ios);
47//!
48//! // For berevity, a Refresh Token is being used here. However, the client can also
49//! // be authenticated using a username and password.
50//! //
51//! // See `Client::login` for more information.
52//! let refresh_token = Credentials::RefreshToken("".to_string());
53//!
54//! client.login(refresh_token)
55//! .await
56//! .expect("Logging in with a valid refresh token should not fail");
57//!
58//! let locations = client.get_locations()
59//! .await
60//! .expect("Getting locations should not fail");
61//!
62//! let location = locations
63//! .first()
64//! .expect("There should be at least one location");
65//!
66//! let listener = location.listen_for_events(|event, sink| async move {
67//! // The sink can be used to send events to Ring.
68//! println!("New event: {:#?}", event);
69//! })
70//! .await
71//! .expect("Creating a listener should not fail");
72//!
73//! // Wait for the listener to finish.
74//! listener
75//! .join()
76//! .await
77//! # });
78//!```
79//!
80//! ## Listing Devices
81//!
82//! ```no_run
83//! use ring_client::Client;
84//!
85//! use ring_client::authentication::Credentials;
86//! use ring_client::OperatingSystem;
87//!
88//! # tokio_test::block_on(async {
89//! let client = Client::new("Home Automation", "mock-system-id", OperatingSystem::Ios);
90//!
91//! // For berevity, a Refresh Token is being used here. However, the client can also
92//! // be authenticated using a username and password.
93//! //
94//! // See `Client::login` for more information.
95//! let refresh_token = Credentials::RefreshToken("".to_string());
96//!
97//! client.login(refresh_token)
98//! .await
99//! .expect("Logging in with a valid refresh token should not fail");
100//!
101//! let devices = client.get_devices()
102//! .await
103//! .expect("Getting devices not fail");
104//!
105//! println!("{:#?}", devices);
106//! # });
107//!```
108//!
109//! ## Contributing
110//!
111//! There are _tons_ of features which could be added to the crate. If you'd like to contribute, please
112//! feel free to open an issue or a pull request.
113//!
114//! Examples of features which could be added:
115//! 1. Better parity between the Ring API and the structs.
116//! 2. Support for streaming video from Ring cameras and doorbells.
117//!
118//! ### Testing
119//!
120//! Many of the tests require a valid Ring account before they can be run, which can be provided
121//! via a Refresh Token being set in the `.env` file.
122//!
123//! The `.env` file can be created by using `.env.example` as a template:
124//! ```sh
125//! cp .env.example .env
126//! ```
127
128//! #### Running tests
129
130//! The tests can be run with:
131//! ```sh
132//! cargo test
133//! ```
134
135mod client;
136mod constant;
137mod helper;
138
139pub use client::*;
140
141#[doc(hidden)]
142pub use helper::OperatingSystem;