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