AgentLink SDK for Rust

AgentLink IM 的 Rust SDK，提供 HTTP 和 MQTT 协议支持。

特性

• 🔌 HTTP Client: RESTful API 完整支持
• 📡 MQTT Client: 实时消息推送
• 🔒 TLS 支持: 内置 TLS（开发环境信任自签名证书）
• 🔄 自动重连: MQTT 断线自动重连
• 📦 零依赖: 纯 Rust 实现，无外部系统依赖

安装

[dependencies]
agentlink-sdk = { git = "https://github.com/your-repo/agentlink-sdk", branch = "main" }

快速开始

基础使用

use agentlink_sdk::{AgentLinkClient, ClientConfig};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // 创建客户端
    let client = AgentLinkClient::new(ClientConfig::default());
    
    // 一键登录并自动连接 MQTT、启动事件循环
    let response = client.login("user@example.com", "123456").await?;
    
    println!("登录成功: {}", response.user.nickname);
    
    // 获取会话列表
    let conversations = client.conversations()
        .get_conversations(&response.token)
        .await?;
    
    println!("会话数量: {}", conversations.conversations.len());
    
    Ok(())
}

配置

use agentlink_sdk::ClientConfig;

let config = ClientConfig {
    api_url: "https://api.agentlink.im/api/v1".to_string(),
    mqtt_broker_url: "mqtts://mqtt.agentlink.im:8883".to_string(),
    token: None,
    user_id: None,
};

let client = AgentLinkClient::new(config);

事件处理

use agentlink_sdk::{
    AgentLinkClient, ClientConfig, ServerEvent,
    MessageReceivedData, MessageDeliveredData, MessageReadData,
    FriendRequestReceivedData, FriendRequestAcceptedData,
    EVENT_MESSAGE_RECEIVED, EVENT_MESSAGE_DELIVERED, EVENT_MESSAGE_READ,
    EVENT_FRIEND_REQUEST_RECEIVED, EVENT_FRIEND_REQUEST_ACCEPTED,
};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = AgentLinkClient::new(ClientConfig::default());

    // ⭐ 直接在 client 上注册事件回调（简化 API）
    client.on(EVENT_MESSAGE_RECEIVED, |event: ServerEvent<MessageReceivedData>| async move {
        println!("收到新消息: {:?}", event.data.content);
    }).await;

    client.on(EVENT_MESSAGE_DELIVERED, |event: ServerEvent<MessageDeliveredData>| async move {
        println!("消息已送达: {}", event.data.message_id);
    }).await;

    client.on(EVENT_FRIEND_REQUEST_RECEIVED, |event: ServerEvent<FriendRequestReceivedData>| async move {
        println!("收到好友请求: 来自 {}", event.data.from_user_id);
    }).await;

    // 登录并自动启动事件循环
    let response = client.login("user@example.com", "123456").await?;
    println!("登录成功: {}", response.user.nickname);

    // 保持程序运行
    tokio::signal::ctrl_c().await?;

    Ok(())
}

完整事件类型

use agentlink_sdk::{
    // 事件常量
    EVENT_MESSAGE_RECEIVED, EVENT_MESSAGE_DELIVERED, EVENT_MESSAGE_READ,
    EVENT_MESSAGE_DELETED, EVENT_UNREAD_COUNT_UPDATED, EVENT_OFFLINE_MESSAGES_BATCH,
    EVENT_FRIEND_REQUEST_RECEIVED, EVENT_FRIEND_REQUEST_ACCEPTED,
    EVENT_FRIEND_REQUEST_REJECTED, EVENT_FRIEND_ADDED, EVENT_FRIEND_REMOVED,
    EVENT_USER_PRESENCE_CHANGED, EVENT_USER_BLOCKED, EVENT_USER_UNBLOCKED,
    EVENT_SYNC_CONVERSATION_LIST, EVENT_SYNC_FRIEND_LIST, EVENT_SYNC_MESSAGE_HISTORY,
    EVENT_SYNC_CONVERSATION_UPDATE, EVENT_SYNC_FRIEND_UPDATE,
    EVENT_SYNC_FRIEND_REQUEST_LIST, EVENT_SYNC_COMPLETE,

    // 事件数据类型
    ServerEvent,
    MessageReceivedData, MessageDeliveredData, MessageReadData,
    MessageDeletedData, UnreadCountUpdatedData, OfflineMessagesBatchData,
    FriendRequestReceivedData, FriendRequestAcceptedData, FriendRequestRejectedData,
    FriendAddedData, FriendRemovedData,
    UserPresenceChangedData, UserBlockedData, UserUnblockedData,
    SyncConversationListData, SyncFriendListData, SyncMessageHistoryData,
    SyncConversationUpdateData, SyncFriendUpdateData, SyncFriendRequestListData,
    SyncCompleteData,
};

API 文档

Services

Service	说明	方法
AuthService	认证相关	login_with_email_code, send_verification_code, check_linkid, set_linkid
UserService	用户相关	get_me, search_users, get_privacy_settings, update_privacy_settings
MessageService	消息相关	get_conversation_messages, send_message, delete_message, trigger_sync
ConversationService	会话相关	get_conversations, create_conversation, join_conversation, leave_conversation
FriendService	好友相关	get_friends, send_friend_request, respond_friend_request, delete_friend

错误处理

use agentlink_sdk::error::SdkError;

match result {
    Ok(data) => println!("成功: {:?}", data),
    Err(SdkError::Http(msg)) => println!("HTTP 错误: {}", msg),
    Err(SdkError::Mqtt(msg)) => println!("MQTT 错误: {}", msg),
    Err(SdkError::Auth(msg)) => println!("认证错误: {}", msg),
    Err(e) => println!("其他错误: {}", e),
}

开发

构建

cd agentlink-sdk/rust
cargo build

测试

cargo test

文档

cargo doc --open

WASM 支持

SDK 提供了 WebAssembly 版本，可在浏览器或 Node.js 中使用。

构建 WASM

cd wasm
./build.sh

在浏览器中使用

<script type="module">
    import init, { JsHttpClient, JsMqttClient, getVersion } from './pkg/agentlink_wasm.js';
    
    await init();
    console.log('SDK Version:', getVersion());
    
    // HTTP Client
    const httpClient = new JsHttpClient('https://api.example.com');
    httpClient.setAuthToken('your-token');
    const user = await httpClient.get('/users/me');
    
    // MQTT Client
    const mqttClient = new JsMqttClient();
    mqttClient.onEvent((event) => console.log('Event:', event));
    await mqttClient.connect('wss://mqtt.example.com/mqtt', 'client-1');
    await mqttClient.subscribe('chat/room/1', 1);
</script>

更多详情见 wasm/README.md。

目录结构

.
├── Cargo.toml
├── core/                   # 核心库（平台无关）
│   └── src/
│       ├── lib.rs
│       ├── error.rs
│       ├── http/
│       ├── mqtt/
│       ├── protocols/
│       └── services/
├── native/                 # Native 平台实现
│   └── src/
├── wasm/                   # WASM 平台实现
│   ├── Cargo.toml
│   ├── src/
│   │   ├── lib.rs
│   │   ├── bindings.rs     # JS 绑定
│   │   ├── http.rs         # Fetch API 实现
│   │   └── mqtt.rs         # WebSocket 实现
│   ├── build.sh
│   └── README.md
└── README.md

依赖

Native

• tokio: 异步运行时
• reqwest: HTTP 客户端
• rumqttc: MQTT 客户端
• serde: 序列化
• chrono: 时间处理
• uuid: UUID 生成

WASM

• wasm-bindgen: WASM/JS 绑定
• web-sys: Web API 绑定
• js-sys: JavaScript 全局绑定
• wasm-bindgen-futures: 异步支持
• serde-wasm-bindgen: 序列化支持

许可证

MIT License