Digisac Rust SDK

Crate inspirado na arquitetura do paytour para consumir a API Digisac, incorporando boas práticas de Rust (macros, traits, builders e otimizações de compilação).

🎯 Funcionalidades Principais

A biblioteca oferece suporte para:

• Autenticação: Token de acesso via variáveis de ambiente
• Webhooks: CRUD completo (listar, criar, atualizar, deletar)
• Mensagens: Envio de mensagens com suporte a mídia e respostas
• CLI Completo: Interface de linha de comando para todos os endpoints
• Servidor HTTP: Wrapper que expõe comandos CLI via HTTP para integração com agentes

📊 Estatísticas

• Endpoints Implementados: 5 (webhooks e mensagens)
• Comandos CLI: 5
• Boas Práticas: Traits, builders, zero-cost abstractions, otimizações de compilação

Instalação

cargo add digisac --git https://github.com/nextlw/parrachos --package digisac

Variáveis de ambiente

Uso como biblioteca

Exemplo básico: Enviar mensagem

use digisac::{
    client::{DigisacClient, SendMessageRequest},
    config::EnvManager,
};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    dotenv::dotenv().ok();

    let env = EnvManager::load()?;
    let token = env.access_token.ok_or("Token não encontrado")?;

    let client = DigisacClient::new(env.api_base_url, token);

    let request = SendMessageRequest::builder()
        .service_id("123".to_string())
        .contact_id("456".to_string())
        .text("Olá!".to_string())
        .build();

    let response = client.send_message(&request).await?;
    println!("Mensagem enviada: {:?}", response);
    Ok(())
}

Exemplo: Gerenciar webhooks

use digisac::client::{DigisacClient, WebhookCreateRequest};

// Criar webhook
let request = WebhookCreateRequest::builder()
    .url("https://example.com/webhook".to_string())
    .events(vec!["message.received".to_string(), "message.sent".to_string()])
    .active(Some(true))
    .build();

let webhook = client.create_webhook(&request).await?;

// Listar webhooks
let webhooks = client.list_webhooks().await?;
println!("Total de webhooks: {}", webhooks.data.len());

CLI

Webhooks

# Listar webhooks
cargo run --bin digisac-cli -- webhooks-list --verbose

# Criar webhook
cargo run --bin digisac-cli -- webhook-create \
  --url "https://example.com/webhook" \
  --events "message.received,message.sent" \
  --active true

# Atualizar webhook
cargo run --bin digisac-cli -- webhook-update \
  --id "webhook-id" \
  --url "https://new-url.com/webhook" \
  --active false

# Deletar webhook
cargo run --bin digisac-cli -- webhook-delete --id "webhook-id"

Mensagens

# Enviar mensagem
cargo run --bin digisac-cli -- mensagem-enviar \
  --service-id "123" \
  --contact-id "456" \
  --text "Olá, como vai?" \
  --verbose

# Enviar mensagem com mídia
cargo run --bin digisac-cli -- mensagem-enviar \
  --service-id "123" \
  --contact-id "456" \
  --text "Veja esta imagem" \
  --media-url "https://example.com/image.jpg"

Servidor HTTP

O servidor HTTP expõe os comandos CLI via HTTP para integração com agentes:

# Iniciar servidor
cargo run --bin digisac-server

# Health check
curl http://localhost:8082/health

# Executar comando via HTTP
curl -X POST http://localhost:8082/cli \
  -H "Content-Type: application/json" \
  -d '{
    "command": "webhooks-list",
    "args": ["--verbose"]
  }'

Integração com Agente

O agente (agenteS.rs) registra automaticamente as seguintes ferramentas:

• digisac_listar_webhooks: Lista webhooks configurados
• digisac_criar_webhook: Cria novo webhook
• digisac_enviar_mensagem: Envia mensagem via Digisac

Configure DIGISAC_SERVER_URL no ambiente do agente para apontar para o servidor Digisac.

Boas Práticas Implementadas

Este crate incorpora as seguintes boas práticas de Rust:

• Traits: DigisacApi para abstração e testes
• Builders: TypedBuilder para construção type-safe de requests
• Zero-cost abstractions: Métodos genéricos com monomorphization
• Error handling: thiserror para erros customizados
• Otimizações: LTO, codegen-units=1, strip symbols em release
• Logging: tracing estruturado com sanitização de tokens

Contribuindo

Contribuições são bem-vindas! Por favor:

1. Faça fork do repositório
2. Crie uma branch para sua feature (git checkout -b feature/nova-funcionalidade)
3. Commit suas mudanças (git commit -am 'Adiciona nova funcionalidade')
4. Push para a branch (git push origin feature/nova-funcionalidade)
5. Abra um Pull Request

Licença

Este projeto está licenciado sob a Licença Apache 2.0 - veja o arquivo LICENSE para detalhes.