@beaver-im/js-sdk 1.0.0

package/README.md

@@ -0,0 +1,275 @@
+# Beaver JS SDK
+
+Beaver 开放平台 JavaScript SDK - 对标飞书/钉钉/企业微信标准
+
+## 🚀 快速开始
+
+### 安装
+
+```bash
+npm install @beaver/js-sdk
+```
+
+或通过 CDN:
+
+```html
+<script src="https://cdn.beaver.im/sdk/beaver-sdk.min.js"></script>
+```
+
+---
+
+## 📦 功能列表
+
+### ✅ 已实现
+
+1. **OAuth 2.0 授权登录** - Web Component + API
+2. **用户信息查询** - 单个/批量获取
+3. **消息发送** - 文本/图片/文件
+4. **群组管理** - 创建/查询/成员管理
+5. **Webhook 配置** - 事件订阅
+
+### 🔮 计划中
+
+- 扫码登录
+- 免登(应用内)
+- 机器人 API
+- 文件上传/下载
+
+---
+
+## 💡 使用示例
+
+### 1️⃣ OAuth 授权登录
+
+#### 方案 A: Web Component (推荐)
+
+```html
+<!-- 添加登录按钮 -->
+<beaver-login 
+  app-id="your_app_id"
+  redirect-uri="https://yoursite.com/callback">
+</beaver-login>
+
+<script type="module">
+  import '@beaver/js-sdk'
+  
+  // 监听登录事件
+  document.querySelector('beaver-login').addEventListener('beaver:login-start', (e) => {
+    console.log('Login started:', e.detail)
+  })
+</script>
+```
+
+#### 方案 B: JavaScript API
+
+```typescript
+import { AuthApi } from '@beaver/js-sdk'
+
+const auth = new AuthApi({
+  appId: 'your_app_id',
+  appSecret: 'your_app_secret',
+  redirectUri: 'https://yoursite.com/callback'
+})
+
+// 发起授权
+auth.login()
+
+// 在回调页面获取 code
+const authResponse = auth.getAuthCodeFromUrl()
+if (authResponse) {
+  // 用 code 换取 token
+  const tokenInfo = await auth.exchangeCodeForToken(authResponse.code)
+  console.log('Access Token:', tokenInfo.accessToken)
+}
+```
+
+---
+
+### 2️⃣ 获取用户信息
+
+```typescript
+import { UserApi } from '@beaver/js-sdk'
+
+const userApi = new UserApi('your_access_token')
+
+// 获取单个用户
+const userInfo = await userApi.getUserInfo('user_123')
+console.log(userInfo.nickName, userInfo.avatar)
+
+// 批量获取用户
+const userList = await userApi.getUserList(['user_123', 'user_456'])
+console.log(userList)
+```
+
+---
+
+### 3️⃣ 完整 OAuth 流程示例
+
+```typescript
+import { AuthApi, UserApi } from '@beaver/js-sdk'
+
+// Step 1: 初始化
+const auth = new AuthApi({
+  appId: 'your_app_id',
+  appSecret: 'your_app_secret',
+  redirectUri: 'https://yoursite.com/callback'
+})
+
+// Step 2: 用户点击登录按钮
+auth.login()
+
+// Step 3: 在回调页面处理
+// URL: https://yoursite.com/callback?code=xxx&state=yyy
+const authResponse = auth.getAuthCodeFromUrl()
+
+if (authResponse) {
+  // Step 4: 用 code 换取 access_token
+  const tokenInfo = await auth.exchangeCodeForToken(authResponse.code)
+  
+  // Step 5: 用 access_token 获取用户信息
+  const userApi = new UserApi(tokenInfo.accessToken)
+  const userInfo = await userApi.getUserInfo('current_user_id')
+  
+  console.log('登录成功!', userInfo)
+}
+```
+
+---
+
+## 🏗️ API 参考
+
+### AuthApi
+
+OAuth 2.0 认证相关 API
+
+#### 构造函数
+
+```typescript
+new AuthApi(config: IAuthConfig)
+```
+
+**参数:**
+- `appId` - 应用 ID
+- `appSecret` - 应用密钥(换取 token 时需要)
+- `redirectUri` - 回调地址
+- `scope` - 授权范围(可选)
+- `state` - CSRF 防护(可选)
+- `baseUrl` - 开放平台地址(默认: https://open.beaver.im)
+
+#### 方法
+
+| 方法 | 说明 | 返回值 |
+|------|------|--------|
+| `buildAuthUrl()` | 构建授权 URL | `string` |
+| `login()` | 发起授权跳转 | `void` |
+| `getAuthCodeFromUrl()` | 从 URL 获取授权码 | `IAuthResponse \| null` |
+| `exchangeCodeForToken(code)` | 用授权码换取 Token | `Promise<ITokenInfo>` |
+
+---
+
+### UserApi
+
+用户信息查询 API
+
+#### 构造函数
+
+```typescript
+new UserApi(accessToken: string, baseUrl?: string)
+```
+
+**参数:**
+- `accessToken` - 访问令牌
+- `baseUrl` - 开放平台地址(可选)
+
+#### 方法
+
+| 方法 | 说明 | 返回值 |
+|------|------|--------|
+| `getUserInfo(userId)` | 获取用户信息 | `Promise<IUserInfo>` |
+| `getUserList(userIds)` | 批量获取用户 | `Promise<IUserInfo[]>` |
+
+---
+
+## 📝 类型定义
+
+```typescript
+interface IAuthConfig {
+  appId: string
+  appSecret?: string
+  redirectUri: string
+  scope?: string
+  state?: string
+  baseUrl?: string
+}
+
+interface ITokenInfo {
+  accessToken: string
+  refreshToken?: string
+  expiresIn: number
+  tokenType: string
+}
+
+interface IUserInfo {
+  userId: string
+  nickName: string
+  avatar?: string
+  phone?: string
+  email?: string
+}
+```
+
+---
+
+## 🔧 开发
+
+### 环境配置
+
+SDK 支持多环境配置，通过 `.env` 文件管理不同环境的 API 地址：
+
+- `.env.dev` - 开发环境（默认）
+- `.env.test` - 测试环境
+- `.env.prod` - 生产环境
+
+### 构建命令
+
+```bash
+# 安装依赖
+pnpm install
+
+# 开发模式（使用 .env.dev 配置）
+pnpm dev
+
+# 构建 - 开发环境
+pnpm build:dev
+
+# 构建 - 测试环境
+pnpm build:test
+
+# 构建 - 生产环境
+pnpm build:prod
+
+# 默认构建（等同于 build:dev）
+pnpm build
+```
+
+### 环境变量说明
+
+| 变量名 | 说明 | 示例 |
+|--------|------|------|
+| `VITE_API_ENV` | 当前环境标识 | dev/test/prod |
+| `VITE_API_BASE` | API 基础地址 | http://127.0.0.1:22000 |
+
+### 在代码中使用
+
+```typescript
+import { API_ENV, API_BASE } from '@beaver/js-sdk/config/env'
+
+console.log('当前环境:', API_ENV) // 'dev' | 'test' | 'prod'
+console.log('API 地址:', API_BASE)
+```
+
+---
+
+## 📄 License
+
+MIT

package/dist/api/auth.d.ts

@@ -0,0 +1,4 @@
+import { IPasswordLoginReq, IPasswordLoginRes } from '../types/api/oauth';
+
+/** 账号密码登录 */
+export declare const passwordLoginApi: (data: IPasswordLoginReq) => Promise<import('../utils/request').IResponseSuccessData<IPasswordLoginRes>>;

package/dist/api/localClient.d.ts

@@ -0,0 +1,4 @@
+import { IQuickSignRes } from '../types/api/localClient';
+
+/** 本机客户端快捷登录（海狸 PC 已登录时） */
+export declare const quickSignApi: (appId: string) => Promise<import('../utils/request').IResponseSuccessData<IQuickSignRes>>;

package/dist/api/qrcode.d.ts

@@ -0,0 +1,8 @@
+import { IGenerateQrCodeReq, IGenerateQrCodeRes, ICheckQrCodeStatusReq, ICheckQrCodeStatusRes } from '../types/api/qrcode';
+
+/** 扫码页地址（写入二维码，供手机 App 打开） */
+export declare function buildScanQrUrl(sceneId: string): string;
+/** 生成扫码登录会话 */
+export declare const generateQrCodeApi: (data: IGenerateQrCodeReq) => Promise<import('../utils/request').IResponseSuccessData<IGenerateQrCodeRes>>;
+/** 查询扫码状态 */
+export declare const checkQrCodeStatusApi: (data: ICheckQrCodeStatusReq) => Promise<import('../utils/request').IResponseSuccessData<ICheckQrCodeStatusRes>>;