Youloge.IM 即时通讯 SDK

Youloge.IM 是一款轻量级、易集成的即时通讯 SDK，基于 WebSocket 实现实时双向通信，支持私聊、群聊、话题等多种会话类型。

✨ 特性

• 🚀 轻量高效 - 体积小，性能优异，无第三方依赖
• 🔌 WebSocket 通信 - 基于 WebSocket 实现实时双向通信
• 📦 请求-响应模式 - 内置队列系统和 Promise 风格的异步调用
• 🎯 事件驱动 - 完善的事件系统，支持生命周期和消息事件监听
• 💾 游标分页 - 支持游标拉取消息，上拉加载历史记录
• 🔧 易集成 - 简洁的 API 设计，快速接入

📦 安装

npm install youloge.im

🚀 快速开始

创建实例

import YIM from 'youloge.im';

const im = YIM.create({
    apikey: 'your-api-key'
});

登录

await im.login({
    userId: 'user-123',
    authorization: 'your-auth-token',
    userName: '张三',
    userAvatar: 'https://example.com/avatar.jpg'
});

监听事件

// 监听 WebSocket 连接就绪
im.on('READY', (wssInstance) => {
    console.log('WebSocket 已连接');
});

// 监听消息接收
im.on('MESSAGE_RECEIVE', (data) => {
    console.log('收到新消息:', data);
});

// 监听登录状态改变
im.on('loginStateChange', (data) => {
    console.log('登录状态:', data);
});

📚 API 文档

实例方法

login(options)

用户登录，建立 WebSocket 连接并验证身份。

参数：

• userId (string) - 用户 ID
• authorization (string) - 认证令牌
• userName (string) - 用户昵称
• userAvatar (string) - 用户头像
• userStatus (number) - 用户状态（1: 在线, 2: 离线）
• userExtra (object) - 扩展信息

返回： Promise<Object>

session(options)

获取会话列表。

参数：

• limit (number) - 每页数量
• cursor (string) - 游标

返回： Promise<Object>

cookies(options)

获取房间/会话详情。

返回： Promise<Object>

contact(options)

获取联系人/通讯录。

返回： Promise<Object>

createTextMessage(content, options)

创建文本消息对象。

参数：

• content (string) - 消息内容
• options (object) - 扩展选项

返回： Object 消息对象

on(event, callback)

监听事件。

off(event, callback)

移除事件监听。

emit(event, ...args)

触发事件。

destroy()

销毁实例。

事件类型

生命周期事件

| 事件名 | 描述 | 参数 | |--------|------|------| | READY | WebSocket 连接就绪 | wssInstance | | ERROR | 错误事件 | error, wssInstance | | CLOSE | 连接关闭 | event, wssInstance |

消息事件

| 事件名 | 描述 | 参数 | |--------|------|------| | MESSAGE | 所有消息 | message, wssInstance | | MESSAGE_RECEIVE | 消息接收 | data, wssInstance | | MESSAGE_SEND | 消息发送 | data, wssInstance | | MESSAGE_READ | 消息已读 | data, wssInstance | | MESSAGE_DELIVERED | 消息已送达 | data, wssInstance | | MESSAGE_REVOKED | 消息已撤回 | data, wssInstance | | MESSAGE_DELETED | 消息已删除 | data, wssInstance |

状态事件

| 事件名 | 描述 | 参数 | |--------|------|------| | loginStateChange | 登录状态改变 | data |

常量

TYPES

{
    USER_STATUS_OFFLINE: 2,  // 离线
    USER_STATUS_ONLINE: 1,   // 在线
    LOGIN: 'login'
}

响应式状态对象

• YIM.SESSION - 会话列表
• YIM.COOKIES - 房间信息
• YIM.FRIENDS - 好友列表
• YIM.PROFILE - 用户资料
• YIM.MESSAGE - 消息对象

🏗️ 架构设计

核心类

1. WSS - WebSocket 连接管理器

   • 管理连接生命周期
   • 实现请求队列和回调队列
   • 支持自动重连和消息序列化

2. WorkflowManager - 事件流程管理器

   • 事件订阅/发布模式
   • WebSocket 事件分发
   • 统一事件处理

3. CHAT - 业务逻辑层

   • 封装业务 API
   • 状态管理
   • 数据转换

通信协议

请求格式：

{
    "id": "req_1234567890_abc123",
    "method": "login",
    "params": {
        "authorization": "token"
    },
    "timestamp": 1234567890
}

正确返回：

{
    "id": "req_1234567890_abc123",
    "data": {}
}

错误返回：

{
    "id": "req_1234567890_abc123",
    "error": {
        "code": 400,
        "message": "错误信息"
    }
}

📝 示例

完整示例请参考 main.js 文件。

📄 License

MIT