nle_cloud_sdk/lib.rs
1//! # NLECloud SDK for Rust
2//!
3//! An idiomatic, asynchronous, thread-safe Rust SDK for the NLECloud (新大陆物联网云平台) IoT platform.
4//!
5//! ## Overview
6//!
7//! - **Async & Non-blocking**: Built on `tokio` and `reqwest` (with `rustls-tls`).
8//! - **Immutable Client**: [`NleCloudClient`] configured via [`NleCloudClientBuilder`].
9//! - **Generic Envelope Unwrapping**: Responses wrapped in upstream `ResultMsg` envelopes
10//! are automatically intercepted, mapping non-zero API statuses into [`SdkError::Api`].
11//! - **Complete Model Coverage**: Strongly typed structs matching all NLECloud DTOs,
12//! including legacy PascalCase aliases (e.g. [`DeviceInfoDTO`]) for easy migration.
13//!
14//! ## Modules & Core APIs
15//!
16//! The client exposes operations across several domains:
17//!
18//! | Module | Core Methods | Description |
19//! |---|---|---|
20//! | [`api::auth`] | [`login`](NleCloudClient::login), [`get_current_token`](NleCloudClient::get_current_token) | User authentication & token management |
21//! | [`api::projects`] | [`get_projects`](NleCloudClient::get_projects), [`add_project`](NleCloudClient::add_project), [`get_project_sensors`](NleCloudClient::get_project_sensors) | Project lifecycle & hierarchy queries |
22//! | [`api::devices`] | [`get_devices`](NleCloudClient::get_devices), [`get_device_info`](NleCloudClient::get_device_info), [`get_devices_status`](NleCloudClient::get_devices_status) | Device CRUD & online status checks |
23//! | [`api::sensors`] | [`get_sensors`](NleCloudClient::get_sensors), [`add_sensor_datas`](NleCloudClient::add_sensor_datas), [`get_sensor_datas`](NleCloudClient::get_sensor_datas) | Sensor management & telemetry time-series |
24//! | [`api::commands`] | [`send_cmd`](NleCloudClient::send_cmd) | Actuator control & command dispatching |
25//!
26//! ## Quick Start
27//!
28//! ```no_run
29//! use nle_cloud_sdk::prelude::*;
30//!
31//! #[tokio::main]
32//! async fn main() -> Result<()> {
33//! // 1. Build an unauthenticated client
34//! let client = NleCloudClient::builder()
35//! .base_url("http://api.nlecloud.com")
36//! .build()?;
37//!
38//! // 2. Authenticate
39//! let login_res = client.login_with_credentials("your_account", "your_password", false).await?;
40//! println!("Logged in! Token: {}", login_res.access_token);
41//!
42//! // 3. Create an authenticated client clone
43//! let auth_client = client.with_token(login_res.access_token);
44//!
45//! // 4. Query sensors for a device
46//! let sensors = auth_client.get_sensors(10367, None, None).await?;
47//! println!("Sensors found: {}", sensors.len());
48//!
49//! // 5. Dispatch an actuator command (e.g. Turn On = 1)
50//! auth_client.send_cmd(10367, "nl_fan", &1, None).await?;
51//!
52//! Ok(())
53//! }
54//! ```
55
56#![warn(missing_docs)]
57
58pub mod api;
59pub mod client;
60pub(crate) mod envelope;
61pub mod error;
62pub mod models;
63pub mod utils;
64
65pub use client::{DEFAULT_BASE_URL, DEFAULT_TIMEOUT, NleCloudClient, NleCloudClientBuilder};
66pub use error::{Result, SdkError};
67pub use models::*;
68
69/// Convenient prelude module for re-exporting common types.
70pub mod prelude {
71 pub use crate::client::{
72 DEFAULT_BASE_URL, DEFAULT_TIMEOUT, NleCloudClient, NleCloudClientBuilder,
73 };
74 pub use crate::error::{Result, SdkError};
75 pub use crate::models::*;
76}