smsir-rust 0.1.0

A fast, secure, and modular Rust library for interacting with the SMS.ir SMS API, with built-in error handling and a clean, idiomatic interface.
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
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132

<div dir="rtl">

# smsir-rust

[![crates.io](https://img.shields.io/crates/v/smsir-rust.svg)](https://crates.io/crates/smsir-rust) [![docs.rs](https://docs.rs/smsir-rust/badge.svg)](https://docs.rs/smsir-rust/)

کتابخانه smsir-rust یک ابزار امن و سریع برای ارتباط با وب‌سرویس پیامکی [SMS.ir](https://www.sms.ir) در زبان Rust است. این کتابخانه با طراحی ماژولار و مدیریت خطا توسعه داده شده است.

## امکانات

- ارسال پیامک تکی و گروهی
- ارسال پیامک نظیر به نظیر
- ارسال پیامک تایید (OTP) با الگو
- زمان‌بندی و حذف پیام‌های زمان‌بندی‌شده
- دریافت اعتبار و خطوط
- دریافت پیامک‌های دریافتی (جدید، زنده، آرشیو)
- گزارش‌گیری از پیامک‌های ارسال‌شده
- دریافت لیست پک‌های ارسال‌شده
- مدیریت خطاها و توسعه‌پذیری

## نصب

```bash
cargo add smsir-rust
```

یا به صورت دستی در بخش `[dependencies]` فایل `Cargo.toml` خود بنویسید:

```toml
smsir-rust = "0.1.0"
```

سپس:

```powershell
cargo build
```

## راهنمای استفاده

ابتدا کلید API را از پنل SMS.ir دریافت کنید و در کد خود استفاده نمایید.

### نمونه ارسال پیامک تکی
```rust
use smsir_rust::service::SmsService;

let api_key = "YOUR_API_KEY";
let service = SmsService::new(api_key);
let result = service.send_single(
    "شماره فرستنده",
    "متن پیام",
    "شماره گیرنده"
);
match result {
    Ok(response) => println!("ارسال موفق: {:?}", response),
    Err(e) => eprintln!("خطا: {}", e),
}
```

### نمونه ارسال پیامک گروهی
```rust
let mobiles = vec!["09123456789", "09121234567"];
let result = service.send_bulk(
    "شماره فرستنده",
    "متن پیام",
    &mobiles,
    None // برای ارسال آنی
);
```

### نمونه ارسال پیامک تایید با الگو
```rust
let params = vec![("Code", "12345")];
let result = service.send_verify(
    "شماره گیرنده",
    100000, // شناسه الگو
    &params
);
```

### دریافت اعتبار
```rust
let credit = service.get_credit();
```

### دریافت خطوط
```rust
let lines = service.get_lines();
```


## ساختار کتابخانه

- `service`: متدهای اصلی ارتباط با API
- `result`: ساختار داده‌ای پاسخ‌ها
- `error`: مدیریت خطاها


## اجرای تست‌های یکپارچه (Integration Tests)

برای اجرای تست‌های integration و اطمینان از صحت عملکرد کتابخانه، باید چند متغیر محیطی را با مقادیر واقعی خود مقداردهی کنید. این متغیرها به تست‌های مختلف برای ارسال پیامک و دریافت گزارش نیاز دارند:

- `SMSIR_API_KEY` : کلید API دریافتی از پنل SMS.ir
- `SMSIR_TEST_MOBILE` : شماره موبایل معتبر برای تست (مثلاً 09123456789)
- `SMSIR_TEST_SENDER` : شماره فرستنده فعال در پنل شما (مثلاً 3000...)
- `SMSIR_TEST_TEMPLATE_ID` : شناسه الگوی پیامک تایید (OTP) (مثلاً 123456)
- `SMSIR_TEST_PACK_ID` : یک pack_id معتبر برای تست حذف پیام زمان‌بندی‌شده
- `SMSIR_TEST_MSG_ID` : یک msg_id معتبر برای تست گزارش پیام

> **نکته:** اگر هر یک از این متغیرها مقداردهی نشود، تست مربوطه اجرا نخواهد شد و پیام مناسبی نمایش داده می‌شود.

1. متغیرهای محیطی مورد نیاز را تنظیم کنید (بالا را ببینید).
2. دستور زیر را اجرا کنید:

```bash
cargo test --test integration
```

در صورت موفقیت‌آمیز بودن تست‌ها، خروجی مشابه زیر را مشاهده خواهید کرد:

```
running 8 tests
test integration::test_get_credit ... ok
test integration::test_bulk_send ... ok
...

test result: ok. 8 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out
```

در صورت بروز خطا، پیام خطا نمایش داده خواهد شد. لطفاً اطمینان حاصل کنید که همه متغیرهای محیطی با مقادیر معتبر مقداردهی شده‌اند و به اینترنت متصل هستید.

</div>