nim-web-sdk-ng/README.md

Yunxin IM SDK next generation

网易云信即时通讯 IM Elite SDK，为 web sdk 的下一代版本，提供完善的即时通信功能开发框架，屏蔽其内部复杂细节，对外提供较为简洁的 API 接口，方便第三方应用快速集成即时通信功能。

IM Elite SDK 分为 V1 和 V2 两个版本。V2 对 V1 的 API 接口做了大幅调整，并与其它客户端对齐。其中 V1 版本号 < 1，V2 版本号 >= 10。

## 安装

如果你是新用户，推荐使用 V2 API 的 SDK，安装方式为:

```
npm install nim-web-sdk-ng@">=10"
```

如果你是现有 V1 增强版用户，可使用下面命令安装 SDK。或者使用固定版本号安装

```
npm install nim-web-sdk-ng@"<1"
```

## IM V2

### sdk 选择

sdk 默认提供以下几种形式。其中 sdk 默认入口为 dist/v2/NIM_BROWSER_SDK.js。
注意，v2 暂未提供 QCHAT SDK。v2 IM SDK 接口兼容 v1 IM SDK。所以 v1 文件夹中没有构建 IM SDK。

```
dist/
  |── v2
    ├── NIM_BROWSER_SDK.js       v2 IM 浏览器适配版 UMD 格式
    ├── NIM_MINIAPP_SDK.js       v2 IM 小程序适配版 UMD 格式
    ├── NIM_UNIAPP_SDK.js        v2 IM UNIAPP 适配版 UMD 格式
    ├── NIM_RN_SDK.js            v2 IM RN 适配版 UMD 格式
    ├── CHATROOM_BROWSER_SDK.js  v2 聊天室浏览器适配版 UMD 格式
    ├── CHATROOM_MINIAPP_SDK.js  v2 聊天室小程序适配版 UMD 格式
    ├── CHATROOM_UNIAPP_SDK.js   v2 聊天室 UNIAPP 适配版 UMD 格式
    ├── CHATROOM_RN_SDK.js       v2 聊天室 RN 适配版 UMD 格式
  |── nodejs
    ├── nim.js                   v2 IM Node.js 适配版 ESM 格式
    ├── nim.d.ts                 TypeScript 类型定义入口
    ├── nim/                     TypeScript 类型定义目录
  |── v1
    ├── CHATROOM_BROWSER_SDK.js  v1 聊天室浏览器适配版 UMD 格式
    ├── CHATROOM_MINIAPP_SDK.js  v1 聊天室小程序适配版 UMD 格式
    ├── CHATROOM_UNIAPP_SDK.js   v1 聊天室 UNIAPP 适配版 UMD 格式
    ├── QCHAT_BROWSER_SDK.js     v1 圈组浏览器适配版 UMD 格式
    ├── QCHAT_UNIAPP_SDK.js      v1 圈组浏览器适配版 UMD 格式
```

#### 基础引入例子

```js
// 若使用 IM 能力则引入
import NIM from 'nim-web-sdk-ng'
// 等效于
import NIM from 'nim-web-sdk-ng/dist/v2/NIM_BROWSER_SDK'

// 0.11.0 版开始支持单例模式获取实例, 在此之前通过 new 创建实例
const nim = NIM.getInstance(
  {
    appkey: 'YOUR_APPKEY',
    debugLevel: 'debug',
    apiVersion: 'v2'
  },
  {}
)

nim.V2NIMLoginService.on('onLoginStatus', function (arg1) {
  console.log('收到 V2NIMLoginService 模块的 onLoginStatus 事件', arg1)
})

async function init() {
  try {
    await nim.V2NIMLoginService.login('YOUR_ACCOUNT', 'YOUR_TOKEN', {
      authType: 0
    })
  } catch (err) {
    console.error('login failed cause', err)
  }
}

init()
```

### Node.js 环境

Node.js 版本专为服务端场景设计，支持在 Node.js 环境中使用 NIM SDK 的核心功能。

#### 环境要求

- **Node.js 版本**: >= 20.0.0（使用原生 `fetch`、`FormData`、`Blob` API）
- **模块格式**: ESM（ES Modules）
- **依赖**: `ws`（WebSocket 库，已包含在 SDK 依赖中）

#### 安装

```bash
npm install nim-web-sdk-ng@">=10"
```

#### 引入方式

```js
// Node.js 环境专用入口
import NIM from 'nim-web-sdk-ng/dist/nodejs/nim.js'
```

#### 支持的服务模块

| 服务模块                        | 描述                             |
| ------------------------------- | -------------------------------- |
| `V2NIMLoginService`             | 登录服务                         |
| `V2NIMMessageService`           | 消息服务（发送/接收消息）        |
| `V2NIMMessageLogUtil`           | 消息日志工具（查询历史消息）     |
| `V2NIMMessageExtendUtil`        | 消息扩展工具（快捷评论、PIN 等） |
| `V2NIMLocalConversationService` | 本地会话服务                     |
| `V2NIMConversationService`      | 会话服务                         |
| `V2NIMConversationGroupService` | 会话分组服务                     |
| `V2NIMUserService`              | 用户服务                         |
| `V2NIMFriendService`            | 好友服务                         |
| `V2NIMTeamService`              | 群组服务                         |
| `V2NIMNotificationService`      | 通知服务                         |
| `V2NIMStorageService`           | 存储服务（文件上传下载）         |
| `V2NIMSettingService`           | 设置服务                         |
| `V2NIMSyncService`              | 同步服务                         |
| `V2NIMAIService`                | AI 服务                          |
| `V2NIMSignallingService`        | 信令服务                         |
| `V2NIMPassthroughService`       | 透传服务                         |

#### 基础示例

```js
import NIM from 'nim-web-sdk-ng/dist/nodejs/nim.js'

// 创建实例
const nim = NIM.getInstance({
  appkey: 'YOUR_APPKEY',
  account: 'YOUR_ACCOUNT',
  token: 'YOUR_TOKEN',
  debugLevel: 'debug',
  apiVersion: 'v2'
})

// 监听登录状态
nim.V2NIMLoginService.on('onLoginStatus', (status) => {
  console.log('登录状态:', status)
})

nim.V2NIMLoginService.on('onConnectStatus', (status) => {
  console.log('连接状态:', status)
})

// 登录
async function main() {
  try {
    await nim.V2NIMLoginService.login('YOUR_ACCOUNT', 'YOUR_TOKEN')
    console.log('登录成功')

    // 发送文本消息
    const message = nim.V2NIMMessageCreator.createTextMessage('Hello from Node.js!')
    const conversationId = nim.V2NIMConversationIdUtil.p2pConversationId('TARGET_ACCOUNT')
    await nim.V2NIMMessageService.sendMessage(message, conversationId)
    console.log('消息发送成功')
  } catch (err) {
    console.error('操作失败:', err)
  }
}

main()
```

#### 发送图片消息

```js
import NIM from 'nim-web-sdk-ng/dist/nodejs/nim.js'
import path from 'path'

const nim = NIM.getInstance({
  appkey: 'YOUR_APPKEY',
  account: 'YOUR_ACCOUNT',
  token: 'YOUR_TOKEN',
  apiVersion: 'v2'
})

async function sendImage() {
  await nim.V2NIMLoginService.login('YOUR_ACCOUNT', 'YOUR_TOKEN')

  // 使用文件路径创建图片消息
  const imagePath = path.join(process.cwd(), 'image.png')
  const message = nim.V2NIMMessageCreator.createImageMessage(imagePath, 'image.png')

  const conversationId = nim.V2NIMConversationIdUtil.p2pConversationId('TARGET_ACCOUNT')

  // 发送消息，支持上传进度回调
  const result = await nim.V2NIMMessageService.sendMessage(message, conversationId, {}, (progress) => {
    console.log(`上传进度: ${Math.round(progress * 100)}%`)
  })

  console.log('图片发送成功:', result.attachment?.url)
}

sendImage()
```

#### 查询历史消息

```js
async function getHistory() {
  const conversationId = nim.V2NIMConversationIdUtil.p2pConversationId('TARGET_ACCOUNT')

  const messages = await nim.V2NIMMessageLogUtil.getMessageList({
    conversationId,
    limit: 50
  })

  messages.forEach((msg) => {
    console.log(`[${msg.senderId}]: ${msg.text || msg.messageType}`)
  })
}
```

#### TypeScript 支持

Node.js 版本提供完整的 TypeScript 类型定义：

```typescript
import NIM from 'nim-web-sdk-ng/dist/nodejs/nim.js'
import type V2NIM from 'nim-web-sdk-ng/dist/nodejs/nim'

const nim: V2NIM = NIM.getInstance({
  appkey: 'YOUR_APPKEY',
  account: 'YOUR_ACCOUNT',
  token: 'YOUR_TOKEN',
  apiVersion: 'v2'
})
```

#### 注意事项

1. **内存存储**: Node.js 版本使用内存实现 localStorage，数据不会持久化。进程重启后会话和消息缓存将丢失。

2. **网络状态**: 网络状态检测返回固定的"已连接"状态，不支持实时网络状态变化监听。

3. **电源状态**: 电源状态相关 API 为存根实现，不提供实际功能。

4. **文件上传**: 支持通过文件路径上传本地文件，使用原生 `FormData` 和 `fetch` API。

5. **WebSocket**: 使用 `ws` 库实现 WebSocket 连接，需确保网络环境允许 WebSocket 连接。

6. **长连接管理**: 服务端场景建议实现心跳检测和断线重连逻辑，确保连接稳定性。

## IM V1

### sdk 选择

sdk 默认提供以下几种形式

```
dist/
├── CHATROOM_BROWSER_SDK.js  聊天室浏览器适配版 UMD 格式
├── CHATROOM_MINIAPP_SDK.js  聊天室小程序适配版 UMD 格式
├── CHATROOM_UNIAPP_SDK.js   聊天室 UNIAPP 适配版 UMD 格式
├── NIM_BROWSER_SDK.js       IM 浏览器适配版 UMD 格式
├── NIM_MINIAPP_SDK.js       IM 小程序适配版 UMD 格式
├── NIM_UNIAPP_SDK.js        IM UNIAPP 适配版 UMD 格式
├── QCHAT_BROWSER_SDK.js     圈组浏览器适配版 UMD 格式
```

#### 基础引入例子

```js
// 若使用 IM 能力则引入
import NIM from 'nim-web-sdk-ng'
// 等效于
import NIM from 'nim-web-sdk-ng/dist/NIM_BROWSER_SDK'

// 0.11.0 版开始支持单例模式获取实例, 在此之前通过 new 创建实例
const nim = NIM.getInstance(
  {
    debugLevel: 'debug',
    appkey: 'YOUR_APPKEY',
    account: 'YOUR_ACCOUNT',
    token: 'YOUR_TOKEN'
  },
  {}
)

async function init() {
  try {
    if (nim.status === 'unconnected' || nim.status === 'waitReconnect') {
      await nim.connect()
    }
  } catch (err) {
    console.error('login failed cause', err)
  }
}

init()
```