@beaver-im/js-sdk 1.0.0 → 1.0.2

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 CHANGED
@@ -1,275 +1,97 @@
1
- # Beaver JS SDK
1
+ # @beaver-im/js-sdk
2
2
 
3
- Beaver 开放平台 JavaScript SDK - 对标飞书/钉钉/企业微信标准
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
- redirect-uri="https://yoursite.com/callback">
51
- </beaver-login>
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
- ```typescript
66
- import { AuthApi } from '@beaver/js-sdk'
24
+ BeaverSDK.register()
67
25
 
68
- const auth = new AuthApi({
69
- appId: 'your_app_id',
70
- appSecret: 'your_app_secret',
71
- redirectUri: 'https://yoursite.com/callback'
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
- const userList = await userApi.getUserList(['user_123', 'user_456'])
101
- console.log(userList)
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
- ```typescript
109
- import { AuthApi, UserApi } from '@beaver/js-sdk'
44
+ ## 登录事件
110
45
 
111
- // Step 1: 初始化
112
- const auth = new AuthApi({
113
- appId: 'your_app_id',
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
- ## 🏗️ API 参考
54
+ | 方式 | 说明 |
55
+ |------|------|
56
+ | 扫码登录 | 展示二维码,手机海狸 App 扫码确认 |
57
+ | 密码登录 | 手机号 / 邮箱 + 密码 |
58
+ | 本机快捷登录 | 本机已登录海狸 PC 时,请求 `127.0.0.1:38794` 一键授权 |
140
59
 
141
- ### AuthApi
60
+ ## Vue / Electron 示例
142
61
 
143
- OAuth 2.0 认证相关 API
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
- ```typescript
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
- - `appId` - 应用 ID
153
- - `appSecret` - 应用密钥(换取 token 时需要)
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
- interface IUserInfo {
213
- userId: string
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
- pnpm install
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
- ## 📄 License
95
+ ## License
274
96
 
275
97
  MIT