# AgentLink SDK for Rust
AgentLink IM 的 Rust SDK，提供 HTTP 和 MQTT 协议支持。
## 特性
- 🔌 **HTTP Client**: RESTful API 完整支持
- 📡 **MQTT Client**: 实时消息推送
- 🔒 **TLS 支持**: 内置 TLS（开发环境信任自签名证书）
- 🔄 **自动重连**: MQTT 断线自动重连
- 📦 **零依赖**: 纯 Rust 实现，无外部系统依赖
## 安装
```tomn
[dependencies]
agentlink-sdk = { git = "https://github.com/your-repo/agentlink-sdk", branch = "main" }
```
## 快速开始
### 基础使用
```rust
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(())
}
```
### 配置
```rust
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);
```
### 事件处理
```rust
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(())
}
```
### 完整事件类型
```rust
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
| `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` |
### 错误处理
```rust
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),
}
```
## 开发
### 构建
```bash
cd agentlink-sdk/rust
cargo build
```
### 测试
```bash
cargo test
```
### 文档
```bash
cargo doc --open
```
## 目录结构
```
rust/
├── Cargo.toml
├── src/
│ ├── lib.rs # 主入口
│ ├── client.rs # AgentLinkClient
│ ├── error.rs # 错误类型
│ ├── event_loop.rs # 事件循环（旧版）
│ ├── events/ # 事件系统
│ │ ├── mod.rs # 事件类型定义
│ │ └── event_loop.rs # 类型安全的事件循环
│ ├── http/ # HTTP 客户端
│ │ ├── mod.rs
│ │ └── client.rs
│ ├── mqtt/ # MQTT 客户端
│ │ ├── mod.rs
│ │ └── client.rs
│ ├── protocols/ # 协议类型
│ │ ├── mod.rs
│ │ ├── auth.rs
│ │ ├── user.rs
│ │ ├── message.rs
│ │ ├── conversation.rs
│ │ ├── friend.rs
│ │ └── events.rs
│ └── services/ # 服务 API
│ ├── mod.rs
│ ├── auth_service.rs
│ ├── user_service.rs
│ ├── message_service.rs
│ ├── conversation_service.rs
│ └── friend_service.rs
└── README.md
```
## 依赖
- `tokio`: 异步运行时
- `reqwest`: HTTP 客户端
- `rumqttc`: MQTT 客户端
- `serde`: 序列化
- `chrono`: 时间处理
- `uuid`: UUID 生成
## 许可证
MIT License