tencentcloud-sms 0.1.0

# tencentcloud-sms

腾讯云短信服务 Rust SDK - 类型安全、异步高性能的短信 API 客户端。

## 特性

- 🚀 异步 API，基于 `tokio` 和 `reqwest`
- 🔒 类型安全，编译期参数检查
- 🔄 自动重试，支持指数退避
- 📝 完整的 API 覆盖（发送、查询、统计、模板、签名等）
- 🛡️ 内置敏感信息保护
- 📊 可选的日志追踪支持

## 安装

在 `Cargo.toml` 中添加依赖：

```toml
[dependencies]
tencentcloud-sms = "0.1"
tokio = { version = "1", features = ["full"] }

# 可选：启用日志功能
# tencentcloud-sms = { version = "0.1", features = ["logging"] }
```

## 快速开始

### 发送短信

```rust
use tencentcloud_sms::{ClientConfig, Credential, SendSmsRequest, SmsClient};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // 创建客户端
    let client = SmsClient::new(
        Credential::long_term("your_secret_id", "your_secret_key"),
        ClientConfig::default(),
    )?;

    // 发送短信
    let request = SendSmsRequest::builder()
        .phone_number_set(vec!["+8613800138000".to_string()])
        .sms_sdk_app_id("your_app_id")
        .template_id("your_template_id")
        .sign_name("your_sign_name")
        .template_param_set(vec!["123456".to_string()])
        .build();

    let result = client.send_sms(request).await?;

    for status in result {
        println!("发送状态: {} - {}", status.code, status.message);
    }

    Ok(())
}
```

### 查询发送状态

```rust
use tencentcloud_sms::{ClientConfig, Credential, PullSmsSendStatusRequest, SmsClient};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = SmsClient::new(
        Credential::long_term("your_secret_id", "your_secret_key"),
        ClientConfig::default(),
    )?;

    let request = PullSmsSendStatusRequest::builder()
        .sms_sdk_app_id("your_app_id")
        .limit(10)
        .build();

    let statuses = client.pull_sms_send_status(request).await?;

    for status in statuses {
        println!("号码: {} - 状态: {}", status.phone_number, status.report_status);
    }

    Ok(())
}
```

### 查询发送统计

```rust
use chrono::{Duration, Local};
use tencentcloud_sms::{ClientConfig, Credential, SendStatusStatisticsRequest, SmsClient};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = SmsClient::new(
        Credential::long_term("your_secret_id", "your_secret_key"),
        ClientConfig::default(),
    )?;

    // 查询最近7天的统计
    let now = Local::now();
    let begin_time = (now - Duration::days(7)).format("%Y%m%d%H").to_string();
    let end_time = now.format("%Y%m%d%H").to_string();

    let request = SendStatusStatisticsRequest::builder()
        .begin_time(begin_time)
        .end_time(end_time)
        .sms_sdk_app_id("your_app_id")
        .limit(10)
        .build();

    let stats = client.send_status_statistics(request).await?;

    println!("总计费条数: {}", stats.fee_count);
    println!("总请求次数: {}", stats.request_count);
    println!("成功请求次数: {}", stats.request_success_count);

    Ok(())
}
```

## 支持的 API

### 短信发送
- `send_sms` - 发送短信

### 状态查询
- `pull_sms_send_status` - 拉取短信发送状态
- `pull_sms_send_status_by_phone_number` - 按号码拉取发送状态
- `pull_sms_reply_status` - 拉取短信回复状态
- `pull_sms_reply_status_by_phone_number` - 按号码拉取回复状态

### 统计分析
- `send_status_statistics` - 发送数据统计
- `callback_status_statistics` - 回执数据统计
- `sms_packages_statistics` - 套餐包统计

### 模板管理
- `describe_sms_template_list` - 查询模板列表
- `add_sms_template` - 添加模板
- `modify_sms_template` - 修改模板
- `delete_sms_template` - 删除模板

### 签名管理
- `describe_sms_sign_list` - 查询签名列表
- `add_sms_sign` - 添加签名
- `modify_sms_sign` - 修改签名
- `delete_sms_sign` - 删除签名

### 其他
- `describe_phone_number_info` - 查询号码信息
- `report_conversion` - 上报转化数据

## 示例

查看 `examples/` 目录获取更多示例：

```bash
# 发送短信
cargo run --example send_sms

# 查询发送状态
cargo run --example query_send_status

# 查询统计数据
cargo run --example statistics

# 查询模板列表
cargo run --example query_templates
```

## 配置

### 环境变量

建议通过环境变量配置敏感信息：

```bash
export TENCENT_SECRET_ID="your_secret_id"
export TENCENT_SECRET_KEY="your_secret_key"
export TENCENT_SMS_APP_ID="your_app_id"
export TENCENT_SMS_SIGN_NAME="your_sign_name"
export TENCENT_SMS_TEMPLATE_ID="your_template_id"
```

### 客户端配置

```rust
use tencentcloud_sms::{ClientConfig, Region, RetryConfig};
use std::time::Duration;

let config = ClientConfig::builder()
    .region(Region::Guangzhou)
    .timeout(Duration::from_secs(10))
    .retry_config(RetryConfig::builder()
        .max_retries(3)
        .initial_backoff(Duration::from_millis(100))
        .max_backoff(Duration::from_secs(5))
        .build())
    .build();
```

## License

MIT