# konduto-rs


SDK não oficial em Rust para a API da [Konduto](https://konduto.com) - Plataforma de análise de prevenção a fraude.

[![Crates.io](https://img.shields.io/crates/v/konduto-rs.svg)](https://crates.io/crates/konduto-rs)
[![Documentation](https://docs.rs/konduto-rs/badge.svg)](https://docs.rs/konduto-rs)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

## Características

-    Cliente HTTP assíncrono completo para a API da Konduto
-    Autenticação integrada (Basic Auth)
-    Tipos fortemente tipados para todas as estruturas de dados
- Suporte a todos os endpoints principais:
  - Envio e consulta de pedidos
  - Atualização de status de pedidos
  - Gerenciamento de Blocklist, Allowlist e Reviewlist
-  **Métricas automáticas** (feature `statsd`):
  - StatsD/DogStatsD nativo
  - Rastreamento de latência, taxa de requisições, erros

## Instalação

Adicione ao seu `Cargo.toml`:

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

# Para habilitar métricas automáticas (opcional)
# konduto-rs = { version = "0.1", features = ["statsd"] }
```

## Configuração

Obtenha sua chave de API no [painel da Konduto](https://dashboard.konduto.com) e configure como variável de ambiente:

```bash
export KONDUTO_API_KEY="sua_chave_api_aqui"
```

## Exemplos de Uso

### Enviando um Pedido para Análise

```rust
use konduto::{KondutoClient, Order, Customer, Payment, PaymentType};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Criar cliente
    let client = KondutoClient::new("sua_api_key".to_string());
    
    // Criar dados do cliente
    let customer = Customer::builder()
        .id("CUSTOMER123")
        .name("João Silva")
        .email("joao@example.com")
        .phone1("+55 11 98765-4321")
        .tax_id("12345678900")
        .build();
    
    // Criar pedido
    let order = Order::builder()
        .id("ORDER123")
        .total_amount(100.0)
        .customer(customer)
        .analyze(true)
        .build();
    
    // Enviar para análise
    let response = client.send_order(&order).await?;
    
    println!("Recomendação: {:?}", response.recommendation);
    println!("Score: {:.2}", response.score);
    
    Ok(())
}
```

### Consultando um Pedido

```rust
use konduto::KondutoClient;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = KondutoClient::new("sua_api_key".to_string());
    
    let order = client.get_order("ORDER123").await?;
    println!("Status: {:?}", order.status);
    println!("Recomendação: {:?}", order.recommendation);
    
    Ok(())
}
```

### Atualizando Status de um Pedido

```rust
use konduto::{KondutoClient, OrderStatus};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = KondutoClient::new("sua_api_key".to_string());
    
    let response = client
        .update_order_status("ORDER123", OrderStatus::Approved)
        .await?;
    
    println!("Status atualizado para: {:?}", response.status);
    
    Ok(())
}
```

### Gerenciando Listas (Blocklist/Allowlist)

```rust
use konduto::{KondutoClient, ListType, ListEntryType};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = KondutoClient::new("sua_api_key".to_string());
    
    // Bloquear email
    client.block_email("fraud@example.com", Some("Fraude confirmada")).await?;
    
    // Permitir email de cliente confiável
    client.allow_email("vip@example.com", Some("Cliente VIP")).await?;
    
    // Bloquear CPF
    client.block_cpf("12345678900", Some("Cliente fraudador")).await?;
    
    // Bloquear IP
    client.block_ip("192.168.1.100", Some("IP suspeito")).await?;
    
    // Consultar item em lista
    let entry = client.get_from_list(
        ListType::Blocklist,
        ListEntryType::Email,
        "fraud@example.com"
    ).await?;
    
    println!("Encontrado na lista: {}", entry.list);
    
    // Remover da lista
    client.remove_from_list(
        ListType::Blocklist,
        ListEntryType::Email,
        "fraud@example.com"
    ).await?;
    
    Ok(())
}
```


## Exemplos Completos

Confira os exemplos completos no diretório `examples/`:

```bash
# Enviar um pedido
cargo run --example send_order

# Gerenciar listas
cargo run --example blocklist

# Métricas automáticas (requer feature statsd)
cargo run --example automatic_metrics --features statsd
```

## Observabilidade e Métricas

A SDK possui suporte nativo para métricas automáticas via StatsD/DogStatsD:

### Métricas Disponíveis

Quando a feature `statsd` está habilitada, a SDK envia automaticamente:

- `konduto.requests.hits` - Taxa de requisições
- `konduto.requests.latency` - Latência (média, P95, P99)
- `konduto.requests.status` - Distribuição de status HTTP
- `konduto.requests.errors` - Taxa de erros

Todas com tags: `method`, `endpoint`, `status`, `latency_bucket`, `sdk:konduto-rs`

## Testes

Execute os testes:

```bash
# Usando just (recomendado)
just test

# Ou usando cargo diretamente
cargo test
```

## 🛠️ Ferramentas de Desenvolvimento

Este projeto usa [just](https://github.com/casey/just) como task runner para facilitar o desenvolvimento.

### Instalação do Just

```bash
# macOS
brew install just

# Linux/Windows
cargo install just
```

### Comandos Úteis

```bash
# Ver todos os comandos disponíveis
just
```
- [Just GitHub](https://github.com/casey/just)
- [Just Documentation](https://just.systems/)
- [Justfile Syntax](https://just.systems/man/en/chapter_20.html)


## Documentação da API

Para mais detalhes sobre a API da Konduto, consulte:
- [Documentação oficial da API Konduto](https://docs.konduto.com/reference/introdu%C3%A7%C3%A3o)

## Contribuindo

Contribuições são bem-vindas! Sinta-se à vontade para:

1. Fazer fork do projeto
2. Criar uma branch para sua feature (`git checkout -b feature/MinhaFeature`)
3. Commit suas mudanças (`git commit -m 'Adiciona MinhaFeature'`)
4. Push para a branch (`git push origin feature/MinhaFeature`)
5. Abrir um Pull Request

## ⚠️ Aviso

Esta é uma SDK **não oficial** para a API da Konduto. Para SDKs oficiais, consulte:
- [PHP SDK](https://github.com/konduto/php-sdk)
- [Java SDK](https://github.com/konduto/java-sdk)
- [.NET SDK](https://github.com/konduto/dotnet-sdk)

## Licença

Este projeto está licenciado sob a licença MIT - veja o arquivo [LICENSE](LICENSE) para detalhes.

## Links Úteis

- [Site da Konduto](https://konduto.com)
- [Documentação da API](https://docs.konduto.com)
- [Dashboard Konduto](https://dashboard.konduto.com)

## Suporte

Para questões relacionadas à API da Konduto, entre em contato com o suporte oficial da Konduto.

Para questões sobre esta SDK, abra uma issue no GitHub.

---

Feito com ❤️ em Rust

