whmcs 0.1.1

Rust client for the WHMCS API
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96

use crate::{
    client::WhmcsClient,
    error::WhmcsError,
    models::auth::{ValidateLoginParams, ValidateLoginResponse},
    resources::endpoint,
};

impl WhmcsClient {
    endpoint!(
        /// This command can be used to validate an email address and password against a registered user in WHMCS.
        ///
        /// If the email address is valid, and the password is correct, a session will be started as part of creating a passwordhash. This session can be used for remote sign-in, (see below) but can affect other aspects of your script if using the `LocalAPI`. A validated login will update the last login time stored for the client account. On success, the `user_id` and `session_token` will be returned. This can be used to establish an authenticated session by setting the session key `‘login_auth_tk’` to the `session_token`.
        ///
        /// **Note:** If session IP validation is enabled, this API call must be executed via the local API to receive a valid hash.
        ///
        /// **Note:** The login functionality provided by this API is superseded by `CreateSsoToken` <https://developers.whmcs.com/api-reference/createssotoken/> for remote login functionality and `OpenID Connect` <https://go.whmcs.com/1993/openid-connect> for authentication services/credential verification. This API may be deprecated in the future given these more robust and modern implementations.
        ///
        /// # Example
        /// ```no_run
        /// # use whmcs::{WhmcsBuilder, models::auth::ValidateLoginParams};
        /// # async fn run() -> Result<(), whmcs::WhmcsError> {
        /// let client = WhmcsBuilder::new()
        ///     .url("https://example.com/includes/api.php")
        ///     .api_identifier("id")
        ///     .api_secret("secret")
        ///     .build()
        ///     .expect("Failed to build client");
        ///
        /// let response = client
        ///     .validate_login(ValidateLoginParams::default()
        ///         .email("user@example.com")
        ///         .password("password"))
        ///     .await;
        /// # Ok(())
        /// # }
        /// ```
        ///
        /// # Reference
        /// <https://developers.whmcs.com/api-reference/validatelogin/>
        ///
        /// # Errors
        /// Will return a [`WhmcsError`](`crate::WhmcsError`) if the API returns an error.
        validate_login,
        "ValidateLogin",
        ValidateLoginParams,
        ValidateLoginResponse
    );
}

#[cfg(test)]
mod tests {
    use crate::{error::WhmcsError, models::auth::ValidateLoginParams, test::get_test_client};

    fn test_password() -> String {
        std::env::var("PASSWORD").expect("set PASSWORD for validate_login integration tests")
    }

    #[ignore = "Require WHMCS instance"]
    #[tokio::test]
    async fn validate_login_success() {
        let client = get_test_client();
        let email = std::env::var("EMAIL")
            .expect("set EMAIL to a WHMCS account email for validate_login integration tests");
        let password = test_password();

        let response = client
            .validate_login(
                ValidateLoginParams::default()
                    .email(email)
                    .password(password),
            )
            .await
            .expect("validate_login should succeed with correct credentials");

        assert_ne!(response.user_id.as_u32(), 0);
    }

    #[ignore = "Require WHMCS instance"]
    #[tokio::test]
    async fn validate_login_wrong_password() {
        let client = get_test_client();
        let email = std::env::var("EMAIL")
            .expect("set EMAIL to a WHMCS account email for validate_login integration tests");

        let err = client
            .validate_login(
                ValidateLoginParams::default()
                    .email(email)
                    .password("definitely-not-the-real-password-9f3a2c1e"),
            )
            .await
            .expect_err("wrong password should yield an API error");

        assert!(matches!(err, WhmcsError::ApiError(_)));
    }
}