nle-cloud-sdk 0.1.1

Unofficial asynchronous Rust SDK for the NLECloud (新大陆物联网云平台) IoT platform
Documentation
use crate::client::NleCloudClient;
use crate::error::{Result, SdkError};
use crate::models::{
    SensorBaseInfoDto, SensorDataFuzzyQryPagingParas, SensorDataInfoDto,
    SensorDataJuHeQryPagingParas, SensorDataListAddDto, SensorDataPageDto,
};
use reqwest::Method;
use serde::Serialize;

impl NleCloudClient {
    /// Queries a single sensor by device ID and sensor tag.
    ///
    /// Endpoint: `GET /devices/{deviceid}/sensors/{apitag}`
    pub async fn get_sensor_info(
        &self,
        device_id: i32,
        api_tag: &str,
        token_override: Option<&str>,
    ) -> Result<SensorBaseInfoDto> {
        if device_id <= 0 {
            return Err(SdkError::InvalidParameter(
                "device_id must be greater than zero".to_string(),
            ));
        }
        if api_tag.trim().is_empty() {
            return Err(SdkError::InvalidParameter(
                "api_tag cannot be empty".to_string(),
            ));
        }

        let path = format!("devices/{}/sensors/{}", device_id, api_tag);
        self.request_with_envelope(Method::GET, &path, &[], None, token_override, true)
            .await
    }

    /// Queries a single sensor by device ID and sensor tag, with optional `is_private` flag.
    ///
    /// Endpoint: `GET /devices/{deviceid}/sensors/{apitag}?isPrivate={isPrivate}`
    pub async fn get_sensor_info_with_options(
        &self,
        device_id: i32,
        api_tag: &str,
        is_private: Option<bool>,
        token_override: Option<&str>,
    ) -> Result<SensorBaseInfoDto> {
        if device_id <= 0 {
            return Err(SdkError::InvalidParameter(
                "device_id must be greater than zero".to_string(),
            ));
        }
        if api_tag.trim().is_empty() {
            return Err(SdkError::InvalidParameter(
                "api_tag cannot be empty".to_string(),
            ));
        }

        let path = format!("devices/{}/sensors/{}", device_id, api_tag);
        let mut query = Vec::new();
        let is_private_str;
        if let Some(p) = is_private {
            is_private_str = p.to_string();
            query.push(("isPrivate", is_private_str.as_str()));
        }

        self.request_with_envelope(Method::GET, &path, &query, None, token_override, true)
            .await
    }

    /// Queries sensors for a device, optionally filtering by sensor tags.
    ///
    /// Endpoint: `GET /devices/{deviceid}/sensors?apitags={apitags}`
    pub async fn get_sensors(
        &self,
        device_id: i32,
        api_tags: Option<&str>,
        token_override: Option<&str>,
    ) -> Result<Vec<SensorBaseInfoDto>> {
        self.get_sensors_with_options(device_id, api_tags, None, token_override)
            .await
    }

    /// Queries sensors for a device, with optional filtering by sensor tags and `is_private` flag.
    ///
    /// Endpoint: `GET /devices/{deviceid}/sensors?apitags={apitags}&isPrivate={isPrivate}`
    pub async fn get_sensors_with_options(
        &self,
        device_id: i32,
        api_tags: Option<&str>,
        is_private: Option<bool>,
        token_override: Option<&str>,
    ) -> Result<Vec<SensorBaseInfoDto>> {
        if device_id <= 0 {
            return Err(SdkError::InvalidParameter(
                "device_id must be greater than zero".to_string(),
            ));
        }

        let path = format!("devices/{}/sensors", device_id);
        let mut query = Vec::new();
        if let Some(tags) = api_tags {
            query.push(("apitags", tags));
        }
        let is_private_str;
        if let Some(p) = is_private {
            is_private_str = p.to_string();
            query.push(("isPrivate", is_private_str.as_str()));
        }

        self.request_with_envelope(Method::GET, &path, &query, None, token_override, true)
            .await
    }

    /// Adds a new sensor, actuator, or camera to a device and returns its ID.
    ///
    /// Endpoint: `POST /devices/{deviceid}/sensors`
    pub async fn add_sensor<T: Serialize>(
        &self,
        device_id: i32,
        sensor: &T,
        token_override: Option<&str>,
    ) -> Result<i32> {
        if device_id <= 0 {
            return Err(SdkError::InvalidParameter(
                "device_id must be greater than zero".to_string(),
            ));
        }

        let path = format!("devices/{}/sensors", device_id);
        let body = serde_json::to_value(sensor)?;
        self.request_with_envelope(Method::POST, &path, &[], Some(body), token_override, true)
            .await
    }

    /// Updates an existing sensor, actuator, or camera on a device.
    ///
    /// Endpoint: `PUT /devices/{deviceid}/sensors/{apitag}`
    pub async fn update_sensor<T: Serialize>(
        &self,
        device_id: i32,
        api_tag: &str,
        sensor: &T,
        token_override: Option<&str>,
    ) -> Result<()> {
        if device_id <= 0 {
            return Err(SdkError::InvalidParameter(
                "device_id must be greater than zero".to_string(),
            ));
        }
        if api_tag.trim().is_empty() {
            return Err(SdkError::InvalidParameter(
                "api_tag cannot be empty".to_string(),
            ));
        }

        let path = format!("devices/{}/sensors/{}", device_id, api_tag);
        let body = serde_json::to_value(sensor)?;
        self.request_empty(Method::PUT, &path, &[], Some(body), token_override, true)
            .await
    }

    /// Deletes a sensor from a device.
    ///
    /// Endpoint: `DELETE /devices/{deviceid}/sensors/{apitag}`
    pub async fn delete_sensor(
        &self,
        device_id: i32,
        api_tag: &str,
        token_override: Option<&str>,
    ) -> Result<()> {
        if device_id <= 0 {
            return Err(SdkError::InvalidParameter(
                "device_id must be greater than zero".to_string(),
            ));
        }
        if api_tag.trim().is_empty() {
            return Err(SdkError::InvalidParameter(
                "api_tag cannot be empty".to_string(),
            ));
        }

        let path = format!("devices/{}/sensors/{}", device_id, api_tag);
        self.request_empty(Method::DELETE, &path, &[], None, token_override, true)
            .await
    }

    /// Adds/publishes telemetry data points for one or more sensors on a device.
    ///
    /// Endpoint: `POST /devices/{deviceid}/datas`
    pub async fn add_sensor_datas(
        &self,
        device_id: i32,
        data: &SensorDataListAddDto,
        token_override: Option<&str>,
    ) -> Result<()> {
        if device_id <= 0 {
            return Err(SdkError::InvalidParameter(
                "device_id must be greater than zero".to_string(),
            ));
        }

        let path = format!("devices/{}/datas", device_id);
        let body = serde_json::to_value(data)?;
        self.request_empty(Method::POST, &path, &[], Some(body), token_override, true)
            .await
    }

    /// Queries telemetry data points for a device with pagination and filtering.
    ///
    /// Endpoint: `GET /devices/{deviceid}/datas`
    pub async fn get_sensor_datas(
        &self,
        query: &SensorDataFuzzyQryPagingParas,
        token_override: Option<&str>,
    ) -> Result<SensorDataPageDto> {
        if query.device_id <= 0 {
            return Err(SdkError::InvalidParameter(
                "DeviceId must be greater than zero".to_string(),
            ));
        }

        let path = format!("devices/{}/datas", query.device_id);
        let mut params = Vec::new();
        let method_str = query.method.to_string();
        let page_size_str = query.page_size.to_string();
        let page_index_str = query.page_index.to_string();
        let time_ago_str;

        params.push(("Method", method_str.as_str()));
        params.push(("PageSize", page_size_str.as_str()));
        params.push(("PageIndex", page_index_str.as_str()));
        params.push(("Sort", query.sort.as_str()));

        if let Some(ta) = query.time_ago {
            time_ago_str = ta.to_string();
            params.push(("TimeAgo", time_ago_str.as_str()));
        }
        if let Some(ref tags) = query.api_tags {
            params.push(("ApiTags", tags.as_str()));
        }
        if let Some(ref sd) = query.start_date {
            params.push(("StartDate", sd.as_str()));
        }
        if let Some(ref ed) = query.end_date {
            params.push(("EndDate", ed.as_str()));
        }

        self.request_with_envelope(Method::GET, &path, &params, None, token_override, true)
            .await
    }

    /// Aggregates sensor data over time intervals (minute, hour, day, month) using MIN, MAX, or COUNT.
    ///
    /// Endpoint: `GET /devices/{deviceid}/datas/grouping`
    pub async fn grouping_sensor_datas(
        &self,
        query: &SensorDataJuHeQryPagingParas,
        token_override: Option<&str>,
    ) -> Result<SensorDataInfoDto> {
        if query.device_id <= 0 {
            return Err(SdkError::InvalidParameter(
                "DeviceId must be greater than zero".to_string(),
            ));
        }

        let path = format!("devices/{}/datas/grouping", query.device_id);
        let mut params = Vec::new();
        let group_by_str = query.group_by.to_string();

        params.push(("GroupBy", group_by_str.as_str()));
        params.push(("Func", query.func.as_str()));
        params.push(("StartDate", query.start_date.as_str()));

        if let Some(ref tags) = query.api_tags {
            params.push(("ApiTags", tags.as_str()));
        }
        if let Some(ref ed) = query.end_date {
            params.push(("EndDate", ed.as_str()));
        }

        self.request_with_envelope(Method::GET, &path, &params, None, token_override, true)
            .await
    }

    /// Queries actuator operation execution logs with pagination and filters.
    ///
    /// Endpoint: `GET /devices/{deviceId}/Datas/SensorDataExecLog`
    pub async fn get_actuator_exec_log(
        &self,
        query: &SensorDataFuzzyQryPagingParas,
        token_override: Option<&str>,
    ) -> Result<serde_json::Value> {
        if query.device_id <= 0 {
            return Err(SdkError::InvalidParameter(
                "DeviceId must be greater than zero".to_string(),
            ));
        }

        let path = format!("devices/{}/Datas/SensorDataExecLog", query.device_id);
        let mut params = Vec::new();
        let method_str = query.method.to_string();
        let page_size_str = query.page_size.to_string();
        let page_index_str = query.page_index.to_string();
        let time_ago_str;

        params.push(("Method", method_str.as_str()));
        params.push(("PageSize", page_size_str.as_str()));
        params.push(("PageIndex", page_index_str.as_str()));
        params.push(("Sort", query.sort.as_str()));

        if let Some(ta) = query.time_ago {
            time_ago_str = ta.to_string();
            params.push(("TimeAgo", time_ago_str.as_str()));
        }
        if let Some(ref tags) = query.api_tags {
            params.push(("ApiTags", tags.as_str()));
        }
        if let Some(ref sd) = query.start_date {
            params.push(("StartDate", sd.as_str()));
        }
        if let Some(ref ed) = query.end_date {
            params.push(("EndDate", ed.as_str()));
        }

        self.request_with_envelope(Method::GET, &path, &params, None, token_override, true)
            .await
    }
}