agentlink-sdk 0.1.0

# 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

| 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` |

### 错误处理

```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