XuqmGroup-Vue3SDK/README.md

# XuqmGroup Vue3 SDK 文档

> TypeScript · Vue 3.5 · Vite 6 · 发布至 Nexus npm

## 安装

```bash
npm install @xuqm/vue3-sdk
# 或
yarn add @xuqm/vue3-sdk
```

Vue 3.5+ 作为 peerDependency，不会重复打包。

## 目录结构

```
XuqmGroup-Vue3SDK/src/
├── core/
│   ├── http.ts     # fetch HTTP 客户端
│   └── sdk.ts      # init / setToken / getConfig
├── im/
│   ├── ImClient.ts # WebSocket IM 客户端
│   └── useIm.ts    # Vue Composable 封装
├── types/
│   └── index.ts    # 全部 TypeScript 类型定义
└── index.ts        # 统一导出
```

---

## 快速开始

### 1. 初始化（main.ts）

```typescript
import { init } from '@xuqm/vue3-sdk'

init({
  appKey: 'ak_your_app_key',
  appSecret: 'as_your_app_secret',
  debug: import.meta.env.DEV,
})
```

### 2. 设置 Token

```typescript
import { setToken } from '@xuqm/vue3-sdk'

// 登录后
setToken('eyJ...')

// 登出
setToken(null)
```

---

## HTTP 客户端

```typescript
import { http } from '@xuqm/vue3-sdk'

// 自动附加 Bearer Token，统一解析 ApiResponse
const user = await http.get<UserInfo>('/api/user/profile')
const result = await http.post<LoginResp>('/api/auth/login', { account, password })
```

---

## IM 模块

### useIm Composable（推荐）

```vue
<script setup lang="ts">
import { useIm } from '@xuqm/vue3-sdk'

const { connect, send, revoke, disconnect, messages, connected, error } = useIm()

// 在 onMounted 后连接
onMounted(() => connect())
// onUnmounted 自动调用 disconnect()

function handleSend(text: string) {
  send({
    toId: 'user_002',
    chatType: 'SINGLE',
    msgType: 'TEXT',
    content: text,
  })
}
</script>

<template>
  <div>
    <span>{{ connected ? '已连接' : '未连接' }}</span>
    <div v-for="msg in messages" :key="msg.id">
      <b>{{ msg.fromId }}</b>: {{ msg.content }}
    </div>
  </div>
</template>
```

### ImClient（底层，手动管理）

```typescript
import { ImClient } from '@xuqm/vue3-sdk'

const im = new ImClient()

im.on('connected', () => console.log('connected'))
im.on('message', (msg) => console.log(msg))
im.on('revoke', ({ msgId }) => console.log('revoked', msgId))
im.on('disconnected', (code, reason) => console.log(code, reason))
im.on('error', (e) => console.error(e))

im.connect()

// 发送
im.send({ toId: 'user_002', chatType: 'SINGLE', msgType: 'TEXT', content: 'Hi!' })

// 撤回
im.revoke('msg-uuid')

// 断开
im.disconnect()
```

### 消息类型

```typescript
type MsgType =
  | 'TEXT' | 'IMAGE' | 'VIDEO' | 'AUDIO' | 'FILE'
  | 'CUSTOM' | 'LOCATION' | 'NOTIFY' | 'RICH_TEXT'
  | 'CALL_AUDIO' | 'CALL_VIDEO' | 'FORWARD'

type ChatType = 'SINGLE' | 'GROUP'
```

### ImMessage 结构

```typescript
interface ImMessage {
  id: string
  fromId: string
  toId: string
  chatType: ChatType
  msgType: MsgType
  content: string
  extra?: string
  revoked: boolean
  createdAt: string
}
```

### 自动重连

断线后指数退避重连：3s → 6s → 12s → 最大 30s。`disconnect()` 后停止，`useIm()` 在 `onUnmounted` 中自动调用。

---

## 完整类型导出

```typescript
import type {
  SDKConfig,
  ImMessage,
  SendMessageParams,
  ImEventMap,
  MsgType,
  ChatType,
  ApiResponse,
} from '@xuqm/vue3-sdk'
```

---

## 构建

```bash
# 类型检查
npm run type-check

# 构建（输出 dist/index.es.js + dist/index.cjs.js + dist/index.d.ts）
npm run build
```

## 发版

```bash
# 确认 .npmrc 指向 https://nexus.xuqinmin.com/repository/npm-hosted/
npm login --registry=https://nexus.xuqinmin.com/repository/npm-hosted/
npm run build
npm publish
```