@beaver-im/js-sdk 1.0.0 → 1.0.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +59 -237
- package/dist/beaver-sdk.es.js +538 -557
- package/dist/beaver-sdk.umd.js +16 -16
- package/dist/config/index.d.ts +6 -3
- package/dist/index.d.ts +2 -2
- package/dist/index.vue.d.ts +14 -17
- package/dist/types/api/auth.d.ts +2 -3
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,275 +1,97 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @beaver-im/js-sdk
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
海狸开放平台登录组件:Web Component `<beaver-login>`,支持扫码登录、账号密码登录;登录成功后拿到授权码 `code`,由你的服务端换 Token。
|
|
4
4
|
|
|
5
|
-
##
|
|
6
|
-
|
|
7
|
-
### 安装
|
|
5
|
+
## 安装
|
|
8
6
|
|
|
9
7
|
```bash
|
|
10
|
-
npm install @beaver/js-sdk
|
|
11
|
-
```
|
|
12
|
-
|
|
13
|
-
或通过 CDN:
|
|
14
|
-
|
|
15
|
-
```html
|
|
16
|
-
<script src="https://cdn.beaver.im/sdk/beaver-sdk.min.js"></script>
|
|
8
|
+
npm install @beaver-im/js-sdk
|
|
17
9
|
```
|
|
18
10
|
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
## 📦 功能列表
|
|
22
|
-
|
|
23
|
-
### ✅ 已实现
|
|
24
|
-
|
|
25
|
-
1. **OAuth 2.0 授权登录** - Web Component + API
|
|
26
|
-
2. **用户信息查询** - 单个/批量获取
|
|
27
|
-
3. **消息发送** - 文本/图片/文件
|
|
28
|
-
4. **群组管理** - 创建/查询/成员管理
|
|
29
|
-
5. **Webhook 配置** - 事件订阅
|
|
30
|
-
|
|
31
|
-
### 🔮 计划中
|
|
32
|
-
|
|
33
|
-
- 扫码登录
|
|
34
|
-
- 免登(应用内)
|
|
35
|
-
- 机器人 API
|
|
36
|
-
- 文件上传/下载
|
|
37
|
-
|
|
38
|
-
---
|
|
39
|
-
|
|
40
|
-
## 💡 使用示例
|
|
41
|
-
|
|
42
|
-
### 1️⃣ OAuth 授权登录
|
|
43
|
-
|
|
44
|
-
#### 方案 A: Web Component (推荐)
|
|
11
|
+
## 快速开始
|
|
45
12
|
|
|
46
13
|
```html
|
|
47
|
-
|
|
48
|
-
<beaver-login
|
|
14
|
+
<beaver-login
|
|
49
15
|
app-id="your_app_id"
|
|
50
|
-
|
|
51
|
-
|
|
16
|
+
api-base="https://server.wsrh8888.com"
|
|
17
|
+
oauth-base="https://oauth.wsrh8888.com"
|
|
18
|
+
redirect-url="https://yoursite.com/callback"
|
|
19
|
+
></beaver-login>
|
|
52
20
|
|
|
53
21
|
<script type="module">
|
|
54
|
-
import '@beaver/js-sdk'
|
|
55
|
-
|
|
56
|
-
// 监听登录事件
|
|
57
|
-
document.querySelector('beaver-login').addEventListener('beaver:login-start', (e) => {
|
|
58
|
-
console.log('Login started:', e.detail)
|
|
59
|
-
})
|
|
60
|
-
</script>
|
|
61
|
-
```
|
|
62
|
-
|
|
63
|
-
#### 方案 B: JavaScript API
|
|
22
|
+
import BeaverSDK from '@beaver-im/js-sdk'
|
|
64
23
|
|
|
65
|
-
|
|
66
|
-
import { AuthApi } from '@beaver/js-sdk'
|
|
24
|
+
BeaverSDK.register()
|
|
67
25
|
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
// 发起授权
|
|
75
|
-
auth.login()
|
|
76
|
-
|
|
77
|
-
// 在回调页面获取 code
|
|
78
|
-
const authResponse = auth.getAuthCodeFromUrl()
|
|
79
|
-
if (authResponse) {
|
|
80
|
-
// 用 code 换取 token
|
|
81
|
-
const tokenInfo = await auth.exchangeCodeForToken(authResponse.code)
|
|
82
|
-
console.log('Access Token:', tokenInfo.accessToken)
|
|
83
|
-
}
|
|
26
|
+
document.querySelector('beaver-login').addEventListener('login', (e) => {
|
|
27
|
+
const { authCode } = e.detail.result
|
|
28
|
+
// 交给服务端换取 accessToken
|
|
29
|
+
})
|
|
30
|
+
</script>
|
|
84
31
|
```
|
|
85
32
|
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
### 2️⃣ 获取用户信息
|
|
89
|
-
|
|
90
|
-
```typescript
|
|
91
|
-
import { UserApi } from '@beaver/js-sdk'
|
|
92
|
-
|
|
93
|
-
const userApi = new UserApi('your_access_token')
|
|
33
|
+
若设置了 `redirect-url`,登录成功会跳转到该地址,并在 Query 中带上 `code`,可不监听 `login` 事件。
|
|
94
34
|
|
|
95
|
-
|
|
96
|
-
const userInfo = await userApi.getUserInfo('user_123')
|
|
97
|
-
console.log(userInfo.nickName, userInfo.avatar)
|
|
35
|
+
## 组件属性
|
|
98
36
|
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
### 3️⃣ 完整 OAuth 流程示例
|
|
37
|
+
| 属性 | 类型 | 必填 | 说明 |
|
|
38
|
+
|------|------|------|------|
|
|
39
|
+
| app-id | string | 是 | 开放平台应用 AppID |
|
|
40
|
+
| api-base | string | 否 | 开放 API 网关,默认 `https://server.wsrh8888.com` |
|
|
41
|
+
| oauth-base | string | 否 | 扫码页域名(拼 `/scan?sceneId=`),默认 `https://oauth.wsrh8888.com` |
|
|
42
|
+
| redirect-url | string | 否 | 登录成功后的回跳地址 |
|
|
107
43
|
|
|
108
|
-
|
|
109
|
-
import { AuthApi, UserApi } from '@beaver/js-sdk'
|
|
44
|
+
## 登录事件
|
|
110
45
|
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
appSecret: 'your_app_secret',
|
|
115
|
-
redirectUri: 'https://yoursite.com/callback'
|
|
46
|
+
```javascript
|
|
47
|
+
element.addEventListener('login', (e) => {
|
|
48
|
+
// e.detail: { code: 0, msg: '', result: { authCode: '...' } }
|
|
116
49
|
})
|
|
117
|
-
|
|
118
|
-
// Step 2: 用户点击登录按钮
|
|
119
|
-
auth.login()
|
|
120
|
-
|
|
121
|
-
// Step 3: 在回调页面处理
|
|
122
|
-
// URL: https://yoursite.com/callback?code=xxx&state=yyy
|
|
123
|
-
const authResponse = auth.getAuthCodeFromUrl()
|
|
124
|
-
|
|
125
|
-
if (authResponse) {
|
|
126
|
-
// Step 4: 用 code 换取 access_token
|
|
127
|
-
const tokenInfo = await auth.exchangeCodeForToken(authResponse.code)
|
|
128
|
-
|
|
129
|
-
// Step 5: 用 access_token 获取用户信息
|
|
130
|
-
const userApi = new UserApi(tokenInfo.accessToken)
|
|
131
|
-
const userInfo = await userApi.getUserInfo('current_user_id')
|
|
132
|
-
|
|
133
|
-
console.log('登录成功!', userInfo)
|
|
134
|
-
}
|
|
135
50
|
```
|
|
136
51
|
|
|
137
|
-
|
|
52
|
+
## 登录能力
|
|
138
53
|
|
|
139
|
-
|
|
54
|
+
| 方式 | 说明 |
|
|
55
|
+
|------|------|
|
|
56
|
+
| 扫码登录 | 展示二维码,手机海狸 App 扫码确认 |
|
|
57
|
+
| 密码登录 | 手机号 / 邮箱 + 密码 |
|
|
58
|
+
| 本机快捷登录 | 本机已登录海狸 PC 时,请求 `127.0.0.1:38794` 一键授权 |
|
|
140
59
|
|
|
141
|
-
|
|
60
|
+
## Vue / Electron 示例
|
|
142
61
|
|
|
143
|
-
|
|
62
|
+
```vue
|
|
63
|
+
<template>
|
|
64
|
+
<beaver-login
|
|
65
|
+
:app-id="appId"
|
|
66
|
+
:api-base="apiBase"
|
|
67
|
+
:oauth-base="oauthBase"
|
|
68
|
+
@login="onLogin"
|
|
69
|
+
/>
|
|
70
|
+
</template>
|
|
144
71
|
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
new AuthApi(config: IAuthConfig)
|
|
149
|
-
```
|
|
72
|
+
<script setup>
|
|
73
|
+
import BeaverSDK from '@beaver-im/js-sdk'
|
|
74
|
+
import { onMounted } from 'vue'
|
|
150
75
|
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
- `redirectUri` - 回调地址
|
|
155
|
-
- `scope` - 授权范围(可选)
|
|
156
|
-
- `state` - CSRF 防护(可选)
|
|
157
|
-
- `baseUrl` - 开放平台地址(默认: https://open.beaver.im)
|
|
158
|
-
|
|
159
|
-
#### 方法
|
|
160
|
-
|
|
161
|
-
| 方法 | 说明 | 返回值 |
|
|
162
|
-
|------|------|--------|
|
|
163
|
-
| `buildAuthUrl()` | 构建授权 URL | `string` |
|
|
164
|
-
| `login()` | 发起授权跳转 | `void` |
|
|
165
|
-
| `getAuthCodeFromUrl()` | 从 URL 获取授权码 | `IAuthResponse \| null` |
|
|
166
|
-
| `exchangeCodeForToken(code)` | 用授权码换取 Token | `Promise<ITokenInfo>` |
|
|
167
|
-
|
|
168
|
-
---
|
|
169
|
-
|
|
170
|
-
### UserApi
|
|
171
|
-
|
|
172
|
-
用户信息查询 API
|
|
173
|
-
|
|
174
|
-
#### 构造函数
|
|
175
|
-
|
|
176
|
-
```typescript
|
|
177
|
-
new UserApi(accessToken: string, baseUrl?: string)
|
|
178
|
-
```
|
|
179
|
-
|
|
180
|
-
**参数:**
|
|
181
|
-
- `accessToken` - 访问令牌
|
|
182
|
-
- `baseUrl` - 开放平台地址(可选)
|
|
183
|
-
|
|
184
|
-
#### 方法
|
|
185
|
-
|
|
186
|
-
| 方法 | 说明 | 返回值 |
|
|
187
|
-
|------|------|--------|
|
|
188
|
-
| `getUserInfo(userId)` | 获取用户信息 | `Promise<IUserInfo>` |
|
|
189
|
-
| `getUserList(userIds)` | 批量获取用户 | `Promise<IUserInfo[]>` |
|
|
190
|
-
|
|
191
|
-
---
|
|
192
|
-
|
|
193
|
-
## 📝 类型定义
|
|
194
|
-
|
|
195
|
-
```typescript
|
|
196
|
-
interface IAuthConfig {
|
|
197
|
-
appId: string
|
|
198
|
-
appSecret?: string
|
|
199
|
-
redirectUri: string
|
|
200
|
-
scope?: string
|
|
201
|
-
state?: string
|
|
202
|
-
baseUrl?: string
|
|
203
|
-
}
|
|
204
|
-
|
|
205
|
-
interface ITokenInfo {
|
|
206
|
-
accessToken: string
|
|
207
|
-
refreshToken?: string
|
|
208
|
-
expiresIn: number
|
|
209
|
-
tokenType: string
|
|
210
|
-
}
|
|
76
|
+
onMounted(() => {
|
|
77
|
+
BeaverSDK.register()
|
|
78
|
+
})
|
|
211
79
|
|
|
212
|
-
|
|
213
|
-
|
|
214
|
-
nickName: string
|
|
215
|
-
avatar?: string
|
|
216
|
-
phone?: string
|
|
217
|
-
email?: string
|
|
80
|
+
function onLogin(e) {
|
|
81
|
+
const authCode = e.detail?.result?.authCode
|
|
218
82
|
}
|
|
83
|
+
</script>
|
|
219
84
|
```
|
|
220
85
|
|
|
221
|
-
|
|
222
|
-
|
|
223
|
-
## 🔧 开发
|
|
224
|
-
|
|
225
|
-
### 环境配置
|
|
226
|
-
|
|
227
|
-
SDK 支持多环境配置,通过 `.env` 文件管理不同环境的 API 地址:
|
|
228
|
-
|
|
229
|
-
- `.env.dev` - 开发环境(默认)
|
|
230
|
-
- `.env.test` - 测试环境
|
|
231
|
-
- `.env.prod` - 生产环境
|
|
232
|
-
|
|
233
|
-
### 构建命令
|
|
86
|
+
## 本地开发
|
|
234
87
|
|
|
235
88
|
```bash
|
|
236
|
-
|
|
237
|
-
|
|
238
|
-
|
|
239
|
-
# 开发模式(使用 .env.dev 配置)
|
|
240
|
-
pnpm dev
|
|
241
|
-
|
|
242
|
-
# 构建 - 开发环境
|
|
243
|
-
pnpm build:dev
|
|
244
|
-
|
|
245
|
-
# 构建 - 测试环境
|
|
246
|
-
pnpm build:test
|
|
247
|
-
|
|
248
|
-
# 构建 - 生产环境
|
|
249
|
-
pnpm build:prod
|
|
250
|
-
|
|
251
|
-
# 默认构建(等同于 build:dev)
|
|
252
|
-
pnpm build
|
|
253
|
-
```
|
|
254
|
-
|
|
255
|
-
### 环境变量说明
|
|
256
|
-
|
|
257
|
-
| 变量名 | 说明 | 示例 |
|
|
258
|
-
|--------|------|------|
|
|
259
|
-
| `VITE_API_ENV` | 当前环境标识 | dev/test/prod |
|
|
260
|
-
| `VITE_API_BASE` | API 基础地址 | http://127.0.0.1:22000 |
|
|
261
|
-
|
|
262
|
-
### 在代码中使用
|
|
263
|
-
|
|
264
|
-
```typescript
|
|
265
|
-
import { API_ENV, API_BASE } from '@beaver/js-sdk/config/env'
|
|
266
|
-
|
|
267
|
-
console.log('当前环境:', API_ENV) // 'dev' | 'test' | 'prod'
|
|
268
|
-
console.log('API 地址:', API_BASE)
|
|
89
|
+
npm install
|
|
90
|
+
npm run build
|
|
269
91
|
```
|
|
270
92
|
|
|
271
|
-
|
|
93
|
+
产物:`dist/beaver-sdk.es.js`、`dist/beaver-sdk.umd.js`。
|
|
272
94
|
|
|
273
|
-
##
|
|
95
|
+
## License
|
|
274
96
|
|
|
275
97
|
MIT
|