BoxIM SDK for Rust

A Rust SDK for connecting to BoxIM platform, providing real-time messaging via WebSocket and REST API access.

Features

• WebSocket Real-time Messaging: Persistent connection with automatic reconnection and heartbeat
• REST API Client: User management, group operations, message sending
• Event Handlers: Register callbacks for messages, connection events
• Bot Discovery: Search and match bots by capabilities
• Flexible Configuration: YAML/JSON config files + environment variables

Installation

Add to your Cargo.toml:

[dependencies]
boxim-sdk-rust = "0.1.0"
tokio = { version = "1", features = ["full"] }

Quick Start

use boxim_sdk_rust::{BoxIMConfig, BoxIMProvider};
use std::sync::Arc;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let config = BoxIMConfig {
        enabled: true,
        platform_url: "https://your-platform.com".to_string(),
        ws_url: "wss://your-ws-server.com/ws".to_string(),
        username: "your_username".to_string(),
        password: "your_password".to_string(),
        ..Default::default()
    };

    let provider = Arc::new(BoxIMProvider::new(config.into()));

    // Register message handler
    provider.on_message(|msg| {
        println!("Received: {} - {}", msg.sender_name, msg.content);
    }).await;

    // Connect
    provider.connect().await?;

    // Send a message
    provider.send_message("Hello!", Some(group_id), None).await?;

    // Keep running...
    tokio::signal::ctrl_c().await?;

    provider.disconnect().await;
    Ok(())
}

Core Components

BoxIMProvider

High-level provider combining API and WebSocket client:

use boxim_sdk_rust::BoxIMProvider;

let provider = BoxIMProvider::new(config);
provider.connect().await?;
provider.send_message("content", Some(group_id), None).await?;
provider.on_message(|msg| { /* handle */ }).await;
provider.disconnect().await;

BoxIMAPI

REST API client for server operations:

use boxim_sdk_rust::BoxIMAPI;

let mut api = BoxIMAPI::new(config);
api.login().await?;

// Send messages
api.send_private_message(user_id, "Hello").await?;
api.send_group_message(group_id, "Hello", None).await?;

// User management
let users = api.get_user_list(1, 20).await?;
let bots = api.search_users("logistics").await?;

// Group operations
let group = api.create_group("My Group", "Notice", None).await?;

BoxIMTools

Bot search and capability matching:

use boxim_sdk_rust::BoxIMTools;

let tools = BoxIMTools::new(api);

// Get all bots
let all_bots = tools.get_all_bots().await?;

// Search by keyword
let results = tools.search_bots("logistics").await?;

// Match bots by problem description
let matched = tools.match_bots_by_problem("I need to track my delivery").await?;

BoxIMClient

Low-level WebSocket client with event handlers:

use boxim_sdk_rust::BoxIMClient;

let client = BoxIMClient::new(config, api);

// Register handlers
client.on_message(|msg| { /* all messages */ }).await;
client.on_group_message(group_id, |msg| { /* group-specific */ }).await;
client.on_connect(|| println!("Connected!")).await;
client.on_disconnect(|| println!("Disconnected!")).await;

client.start().await?;

Configuration

Via Config File

Create boxim_config.yaml:

enabled: true
platform_url: https://your-platform.com
ws_url: wss://your-ws-server.com/ws
username: your_username
password: your_password
timeout: 30.0
max_retries: 3
auto_reconnect: true
log_level: INFO

Or boxim_config.json:

{
  "enabled": true,
  "platform_url": "https://your-platform.com",
  "ws_url": "wss://your-ws-server.com/ws",
  "username": "your_username",
  "password": "your_password"
}

Via Environment Variables

export BOXIM_PLATFORM_URL=https://your-platform.com
export BOXIM_WS_URL=wss://your-ws-server.com/ws
export BOXIM_USERNAME=your_username
export BOXIM_PASSWORD=your_password

Environment variables take precedence over config files.

Message Types

pub enum MessageType {
    Text,   // 0
    Image,  // 1
    File,   // 2
    Audio,  // 3
    Video,  // 4
    // System messages: Recall, Readed, Receipt, TipTime, TipText
}

Dependencies

• tokio - Async runtime
• reqwest - HTTP client
• tokio-tungstenite - WebSocket
• serde - Serialization
• config - Configuration management

---

Publishing to crates.io

Prerequisites

1. Create an account at crates.io
2. Install cargo-login and authenticate:

cargo login

This stores your API token in ~/.cargo/credentials.

Prepare Your Crate

1. Ensure version is updated - Each release must have a unique version.

2. Run tests:

cargo test

4. Build and check:

cargo login

cargo build --release
cargo package

# For a dry run (recommended first time):
cargo publish --dry-run

cargo publish

# Verify the package is live
cargo search boxim-sdk-rust

# Or check on crates.io
open https://crates.io/crates/boxim-sdk-rust

Version Updates

# 1. Update version in Cargo.toml
# 2. Commit your changes
git add -A && git commit -m "Bump version to 0.2.0"

# 3. Tag the release
git tag v0.2.0
git push origin main --tags

# 4. Publish
cargo publish

Common Issues

Issue	Solution
"name already exists"	Choose a different crate name in Cargo.toml
"max upload size exceeded"	Reduce dependencies or split into multiple crates
"authentication required"	Run cargo login again

For more details, see the crates.io guide.