# @xuqm/rn-im

XuqmGroup RN SDK IM 模块。提供 WebSocket 实时通信、会话管理、消息收发、群组管理、关系链管理。

## 安装

```bash
yarn add @xuqm/rn-im @nozbe/watermelondb
```

Peer dependencies：`@nozbe/watermelondb >= 0.27.0`，`react-native >= 0.76`

## 使用

**无需手动初始化。** `XuqmSDK.setUserInfo({ userId, userSig })` 被调用时，SDK 自动完成 IM 登录。

```ts
import { ImSDK } from '@xuqm/rn-im'

// 发送消息
await ImSDK.sendTextMessage('user_002', 'SINGLE', 'Hello!')

// 获取会话列表
const conversations = await ImSDK.listConversations()

// 监听新消息
ImSDK.addListener({
  onMessage: (msg) => console.log('新消息:', msg),
  onConnected: () => console.log('IM 已连接'),
})
```

## API

### 连接管理

| API | 说明 |
|-----|------|
| `ImSDK.login(userId, userSig)` | 手动登录（通常不需要直接调用） |
| `ImSDK.refreshToken(userSig)` | 刷新 userSig（过期时调用） |
| `ImSDK.disconnect()` | 断开连接 |
| `ImSDK.reconnect()` | 重新连接 |
| `ImSDK.isConnected()` | 检查连接状态 |

### 消息 API

| API | 说明 |
|-----|------|
| `ImSDK.sendMessage(toId, chatType, msgType, content, mentionedUserIds?)` | 发送消息 |
| `ImSDK.sendTextMessage(toId, chatType, content, mentionedUserIds?)` | 发送文本 |
| `ImSDK.sendImageMessage(toId, chatType, localUri, width?, height?)` | 发送图片 |
| `ImSDK.sendVideoMessage(toId, chatType, localUri, thumbnailUri?, duration?)` | 发送视频 |
| `ImSDK.sendAudioMessage(toId, chatType, localUri, duration)` | 发送语音 |
| `ImSDK.sendFileMessage(toId, chatType, localUri, filename, size)` | 发送文件 |
| `ImSDK.sendQuoteMessage(toId, chatType, quotedMsgId, quotedContent, text)` | 引用回复 |
| `ImSDK.sendLocationMessage(toId, chatType, latitude, longitude, title?, address?)` | 发送位置 |
| `ImSDK.revokeMessage(messageId)` | 撤回消息 |
| `ImSDK.editMessage(messageId, content)` | 编辑消息 |

### 会话 API

| API | 说明 |
|-----|------|
| `ImSDK.listConversations()` | 获取会话列表 |
| `ImSDK.subscribeConversations(callback)` | 订阅会话变更（返回 unsubscribe） |
| `ImSDK.markRead(targetId, chatType?)` | 标记已读 |
| `ImSDK.deleteConversation(targetId, chatType)` | 删除会话 |
| `ImSDK.getTotalUnreadCount()` | 获取总未读数 |

### 历史消息

| API | 说明 |
|-----|------|
| `ImSDK.fetchHistory(toId, page?, size?)` | 获取单聊历史（优先本地缓存） |
| `ImSDK.fetchGroupHistory(groupId, page?, size?)` | 获取群聊历史 |
| `ImSDK.fetchHistoryWithFilters(toId, params)` | 按条件查询历史 |
| `ImSDK.searchMessages(params)` | 搜索消息（本地 WatermelonDB） |
| `ImSDK.locateHistoryPage(toId, messageId)` | 定位消息所在页 |

### 群组 API

| API | 说明 |
|-----|------|
| `ImSDK.createGroup(name, memberIds, groupType?)` | 创建群组 |
| `ImSDK.listGroups()` | 获取群组列表 |
| `ImSDK.getGroupInfo(groupId)` | 获取群组信息 |
| `ImSDK.listGroupMembers(groupId)` | 获取群成员 |
| `ImSDK.addGroupMember(groupId, userId)` | 添加成员 |
| `ImSDK.removeGroupMember(groupId, userId)` | 移除成员 |
| `ImSDK.setGroupRole(groupId, userId, role)` | 设置管理员 |
| `ImSDK.muteGroupMember(groupId, userId, minutes)` | 禁言 |
| `ImSDK.dismissGroup(groupId)` | 解散群组 |

### 关系链 API

| API | 说明 |
|-----|------|
| `ImSDK.listFriends()` | 好友列表 |
| `ImSDK.addFriend(friendId)` | 添加好友 |
| `ImSDK.removeFriend(friendId)` | 删除好友 |
| `ImSDK.sendFriendRequest(toUserId, remark?)` | 发送好友申请 |
| `ImSDK.acceptFriendRequest(requestId)` | 接受好友申请 |
| `ImSDK.addToBlacklist(blockedUserId)` | 加入黑名单 |
| `ImSDK.checkBlacklist(targetUserId)` | 检查黑名单 |

### 事件监听

```ts
ImSDK.addListener({
  onConnected: () => {},
  onDisconnected: (code, reason) => {},
  onMessage: (msg) => {},
  onGroupMessage: (msg) => {},
  onSystemMessage: (msg) => {},
  onRead: (msg) => {},
  onRevoke: (data) => {},
})
ImSDK.removeListener(listener)
```

## 消息类型

`TEXT` / `IMAGE` / `VIDEO` / `AUDIO` / `FILE` / `CUSTOM` / `LOCATION` / `NOTIFY` / `RICH_TEXT` / `CALL_AUDIO` / `CALL_VIDEO` / `QUOTE` / `MERGE` / `REVOKED` / `FORWARD`

## 本地存储

使用 WatermelonDB 进行本地消息缓存，支持离线消息同步和本地搜索。DB 名称由 `appKey + userId` 派生。