Struct Client

pub struct Client { /* private fields */ }

Client used to authenticate and interact with Hive.

Implementations

impl Client

pub async fn get_actions(&self) -> Result<Vec<Action<'_>>, ApiError>

Get all of the Quick Actions setup in the Hive account.

Examples

use hive_client::authentication::{TrustedDevice, User};

let client = hive_client::Client::new("Home Automation").await;

let trusted_device = Some(TrustedDevice::new(
    "device_password",
    "device_group_key",
    "device_key"
));

client.login(User::new("example@example.com", "example", trusted_device))
    .await
    .expect("Login should succeed");

let actions = client.get_actions()
    .await
    .expect("Quick action should be retrieved");

// Activate a quick action
let mut turn_off_heating = actions.into_iter()
    .find(|action| action.data.id == "1234-5678-000-0000")
    .expect("Quick action to turn off heating should exist");

let activated = turn_off_heating.activate().await;

assert!(activated.is_ok());

Errors

Returns an error if the list of Quick Actions could not be retrieved.

impl Client

pub async fn login( &self, user: User, ) -> Result<Option<Arc<TrustedDevice>>, AuthenticationError>

Login to Hive as a User.

This user may optionally have a trusted device associated with their account.

If provided, this induces a simpler login flow, which does not require Two Factor Authentication (ChallengeResponse::SmsMfa).

If not provided, a new device will be automatically confirmed with Hive during the login flow.

Examples

Login with a trusted device

If the user has previously logged in and set the Client as a trusted device , the trusted device can be provided to skip some authentication challenges.

use hive_client::authentication::{TrustedDevice, User};

let client = hive_client::Client::new("Home Automation").await;

let trusted_device = Some(TrustedDevice::new(
    "device_password",
    "device_group_key",
    "device_key"
));

let attempt = client.login(User::new("example@example.com", "example", trusted_device)).await;

// Login shouldn't require any additional challenges, as a remembered device was provided.
assert!(attempt.is_ok());

Login without a trusted device

use hive_client::authentication::{ChallengeResponse, TrustedDevice, User};
use hive_client::AuthenticationError;

let mut client = hive_client::Client::new("Home Automation").await;

let attempt = client.login(User::new("example@example.com", "example", None)).await;

match attempt {
    Ok(trusted_device) => {
       // Login was successful.
       //
       // If a trusted device has been returned this can be used to authenticate in the future.
    },
    Err(AuthenticationError::NextChallenge(challenge)) => {
       // Hive prompted for a challenge to be responded to before
       // authentication can be completed.

       // Handle the challenge accordingly, and respond to the challenge.
       let sms_code = "123456";
       let response = client.respond_to_challenge(ChallengeResponse::SmsMfa(sms_code.to_string())).await;

       assert!(response.is_ok());
    },
    Err(_) => {
      // Login failed, respond accordingly.
    }
}

Errors

Returns an error if Hive did not immediately return an active session.

This can happen if the credentials are invalid, or if Hive prompt for a challenge in order to process (AuthenticationError::NextChallenge).

In the latter case, the caller must generate a ChallengeResponse and call Client::respond_to_challenge to continue with the authentication process.

pub async fn respond_to_challenge( &mut self, challenge_response: ChallengeResponse, ) -> Result<Option<Arc<TrustedDevice>>, AuthenticationError>

Respond to a challenge issued by Hive during the authentication process.

This is typically used to handle Two Factor Authentication (2FA) challenges, but could be any challenge issued by Hive that requires a response from the user (Client::login)

Examples

use hive_client::authentication::{ChallengeResponse, TrustedDevice, User};
use hive_client::AuthenticationError;

let mut client = hive_client::Client::new("Home Automation").await;

let attempt = client.login(User::new("example@example.com", "example", None)).await;

match attempt {
    Ok(trusted_device) => {
        // Login was successful.
        //
        // If a trusted device has been returned this can be used to authenticate in the future.
    },
    Err(AuthenticationError::NextChallenge(challenge)) => {
        // Hive prompted for a challenge to be responded to before
        // authentication can be completed.

        // Handle the challenge accordingly, and respond to the challenge.
        let sms_code = "123456";
        let response = client.respond_to_challenge(ChallengeResponse::SmsMfa(sms_code.to_string())).await;

        if let Ok(trusted_device) = response {
            // Login was successful.
            //
            // If a trusted device has been returned this can be used to authenticate in the future.
        } else {
            // Challenge failed, respond accordingly.
        }
    },
    Err(_) => {
        // Login failed, respond accordingly.
    }
}

Errors

Returns an error if the challenge submission was unsuccessful. If this happens, the caller must check the error type and handle it accordingly.

pub async fn logout(&mut self)

Logout from Hive.

Note: This only clears the client, it does not perform any operations on the Hive Account.

Examples

use hive_client::authentication::{TrustedDevice, User};

let mut client = hive_client::Client::new("Home Automation").await;

let trusted_device = Some(TrustedDevice::new(
    "device_password",
    "device_group_key",
    "device_key"
));

let attempt = client.login(User::new("example@example.com", "example", trusted_device)).await;

// Login shouldn't require any additional challenges, as a remembered device was provided.
assert!(attempt.is_ok());

client.logout().await;

impl Client

pub async fn get_devices(&self) -> Result<Vec<Device>, ApiError>

Get all of the devices associated with the Hive account.

This can include Hubs, Thermostats, Boilers, and other devices.

Examples

use hive_client::authentication::{TrustedDevice, User};
use hive_client::products::{Product, ProductData, State, States};

let client = hive_client::Client::new("Home Automation").await;

let trusted_device = Some(TrustedDevice::new(
    "device_password",
    "device_group_key",
    "device_key"
));

let attempt = client.login(User::new("example@example.com", "example", trusted_device)).await;

if let Ok(_) = attempt {
    // Login was successful

    let devices = client.get_devices()
        .await
        .expect("Devices should be retrieved");
     
    println!("{:?}", devices);
}

Errors

Returns an error if the list of devices could not be retrieved.

impl Client

pub async fn get_products(&self) -> Result<Vec<Product<'_>>, ApiError>

Get all of the Hive products setup in the Hive account.

For example, the Heating or Hot Water products.

Examples

use hive_client::authentication::{TrustedDevice, User};
use hive_client::products::{Product, ProductData, State, States};

let client = hive_client::Client::new("Home Automation").await;

let trusted_device = Some(TrustedDevice::new(
    "device_password",
    "device_group_key",
    "device_key"
));

let attempt = client.login(User::new("example@example.com", "example", trusted_device)).await;

if let Ok(_) = attempt {
    // Login was successful

    let products = client.get_products()
        .await
        .expect("Products should be retrieved");
     
    println!("{:?}", products);
}

Errors

Returns an error if the list of products could not be retrieved.

impl Client

pub async fn get_weather(&self, postcode: &str) -> Result<Weather, ApiError>

Get the current weather according to Hive, for a given postcode.

Examples

use hive_client::authentication::{TrustedDevice, User};
use hive_client::{weather::WeatherData};
use hive_client::weather::Temperature::Celsius;
use hive_client::weather::Weather;

let client = hive_client::Client::new("Home Automation").await;

let trusted_device = Some(TrustedDevice::new(
    "device_password",
    "device_group_key",
    "device_key"
));

client.login(User::new("example@example.com", "example", trusted_device))
    .await
    .expect("Login should succeed");

let Weather { data: WeatherData { temperature, ..}} = client.get_weather("SW1A 1AA")
    .await
    .expect("Weather should be retrieved");

println!("The current temperature is: {temperature}");

Errors

Returns an error if the whether data could not be retrieved.

impl Client

pub async fn new(friendly_name: &str) -> Self

Create a new client.

The friendly name is used to identify the client in the Trusted Device page of the Hive app if the user is authenticating for the first time (does not have a trusted device during Client::login)

Trait Implementations

impl Debug for Client

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.