# Infobip API Rust SDK

![Workflow](https://github.com/infobip-community/infobip-api-rust-sdk/actions/workflows/rust.yml/badge.svg)
[![Crates.io](https://img.shields.io/crates/v/infobip_sdk)](https://crates.io/crates/infobip_sdk)
![Crates.io Downloads](https://img.shields.io/crates/d/infobip_sdk)
![Crates.io](https://img.shields.io/crates/l/infobip_sdk)
![Minimum Rust Version](https://img.shields.io/badge/Rust-%3E%3D1.63-blue)

Client SDK to use the [Infobip API](https://www.infobip.com/docs/api/) with pure Rust.

This crate enables you to use multiple Infobip communication channels, like SMS, 2FA,
WhatsApp, Email, etc. It abstracts the needed HTTP calls, models and validates payloads and
models errors. The module structure is divided by communication channel.

---

## 📡 Supported Channels

Currently, we support the following channels:
- [SMS + 2FA](https://www.infobip.com/docs/api/channels/sms)
- [WhatsApp](https://www.infobip.com/docs/api/channels/whatsapp)
- [Email](https://www.infobip.com/docs/api/channels/email)

More channels to be added in the near future!

## 🔐 Authentication

To use the library, you'll need to set up an [Infobip account](https://www.infobip.com/signup).
Then you can use your API Key and custom base URL to call the endpoints. You can use the
`Configuration::from_env_api_key()` method to load the configuration from the environment. To
do that, set the `IB_API_KEY` and `IB_BASE_URL` variables.

## 📦 Installation

To install the library, run the following command under your project's root directory:

```bash
cargo add infobip_sdk
```

Alternatively, you can add the dependency to your project's `Cargo.toml`

```toml
[dependencies]
infobip_sdk = "<version>"
```

Replace `<version>` with the latest (or desired) release of the library. For example `0.5.0`.

## 🚀 Usage

To use the library, import the client and channel-specific models. Then create a client and
call the associated functions. For example, to send an SMS, you can do this:

```rust
use infobip_sdk::model::sms::{Destination, Message, SendRequestBody};
use infobip_sdk::api::sms::SmsClient;
use infobip_sdk::configuration::Configuration;

#[tokio::main]
async fn main() {
    // Build SMS client with configuration from the environment.
    let sms_client = SmsClient::with_configuration(
        // Load IB_API_KEY and IB_BASE_URL environment variables.
        Configuration::from_env_api_key().unwrap()
    );

    // Create a message.
    let message = Message{
        destinations: Some(vec![Destination::new("123456789012")]),
        text: Some("Your message text".to_string()),
        ..Default::default()
    };

    // Create the SendRequestBody instance.
    let request_body = SendRequestBody::new(vec![message]);

    // Send the SMS.
    let response = sms_client.send(request_body).await.unwrap();

    // Do what you want with the response.
    assert_eq!(response.status, reqwest::StatusCode::OK);
    println!("Response body:\n{}", serde_json::to_string(&response.body).unwrap());
}
```

## 👀 Examples

The best way to learn how to use the library is to look at the official
[docs.rs documentation](https://docs.rs/infobip_sdk/), which has simple examples on how to use
every endpoint. You can also look at integration tests under the [tests](./tests) directory,
which work similarly to how you would use them in a real scenario.

## 🗒 Notes

### Building Payload Models

Structs that represent the models have public fields, so you can either build them with the
provided `new()` functions, with `serde_json::from_str()`, or with the true constructor.
For example, to build a `Message` instance, you can do this:

```rust
let message = Message{
    destinations: Some(vec![Destination::new("123456789012")]),
    text: Some("Your message text".to_string()),
    ..Default::default()
}
```

or this:

```rust
let message: Message = serde_json::from_str(
    r#"
        {
          "destinations": [
            {
              "to": "123456789012"
            }
          ],
          "text": "Your message text"
        }
    "#,
)
.unwrap();
```

or this:

```rust
let destination = Destination {
    message_id: None,
    to: "41793026727".to_string()
};

let message = Message {
    destinations: Some(vec![destination]),
    ..Default::default()
};
```

### Model Validation

Some models have mandatory fields. Optional fields are wrapped in `Option` Enums. Models also
have additional checks to make sure that fields have valid values, when possible. Validation
is done automatically when calling an endpoint, or you can call the `.validate()` method of the
model.

### Using Features

You can speed up compile time by turning only the needed channels as library features.
For example, to only build SMS, add the dependency like this:

```toml
infobip_sdk = { version = "0.5", features = ["sms"] }
```

You can see the complete list of features in the Cargo.toml of the project. Feature names
follow channel names.

## 🧡 Contributing

If you would like to help this project improve, please check our [contributing guide](CONTRIBUTING.md) and [code of conduct](CODE_OF_CONDUCT.md).

## ⚖️ License

This project is licensed under either of

 * Apache License, Version 2.0
   ([LICENSE-APACHE](LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0)
 * MIT license
   ([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT)

at your option.