@seaverse/auth-sdk 0.2.5 → 0.3.0

package/README.md

@@ -10,12 +10,14 @@ SeaVerse Backend API 客户端 SDK - 提供完整的认证、容器管理、技
 - 🔐 **用户认证** - 注册、登录、登出、密码重置
 - 🌐 **OAuth登录** - Google、Discord、GitHub 第三方登录
 - 🎨 **登录UI组件** - 开箱即用的精美登录弹窗
+- ✨ **Toast 通知** - 现代化玻璃态提示，CSS 自动注入
 - 📦 **容器管理** - Container 注册、心跳、状态查询
 - 🛍️ **技能市场** - Marketplace Skills 浏览、安装、卸载
 - 🗣️ **语音服务** - Speech Token 获取
 - 🌍 **多环境支持** - Production、Staging、Development、Local
 - ⚡ **TypeScript** - 完整的类型定义
 - 🔧 **认证集成** - 内置Auth、Hooks系统支持
+- 🔄 **响应格式兼容** - 自动兼容多种API响应格式
 
 ## 安装
 
@@ -80,6 +82,16 @@ const client = new SeaVerseBackendAPIClient({
   baseURL: 'https://custom-api.example.com',
 });
 
+// 方式4: 启用请求重试（默认禁用）
+const client = new SeaVerseBackendAPIClient({
+  appId: 'your app id',
+  retryOptions: {
+    maxRetries: 3,                  // 最多重试 3 次
+    retryDelay: 1000,               // 初始延迟 1000ms，每次重试延迟加倍
+    retryStatusCodes: [408, 429, 500, 502, 503, 504],  // 这些状态码会触发重试
+  },
+});
+
 // 健康检查
 const health = await client.getHealth();
 console.log('Health:', health);
@@ -245,6 +257,12 @@ const authModal = new AuthModal({
     console.log('注册成功:', user);
   },
 
+  // 邀请码需求回调（可选）
+  onInviteCodeRequired: (userId, email) => {
+    console.log('需要邀请码激活账户:', userId, email);
+    // AuthModal 会自动显示邀请码输入界面
+  },
+
   // 错误回调
   onError: (error) => {
     console.error('认证错误:', error.message);
@@ -272,15 +290,35 @@ authModal.hide();
 authModal.destroy();
 ```
 
+**✨ 新特性：自动 Toast 通知**
+
+AuthModal 内置了现代化的 Toast 通知系统，无需额外配置：
+
+```typescript
+// Toast 会自动显示，CSS 自动注入
+// - 注册成功 → 绿色成功提示
+// - 账号已存在 → 黄色警告提示
+// - 登录失败 → 红色错误提示
+// - 重置密码 → 蓝色信息提示
+
+// 你也可以单独使用 Toast（CSS 自动注入）
+import { Toast } from '@seaverse/auth-sdk';
+
+Toast.success('操作成功', '数据已保存');
+Toast.error('操作失败', '请稍后重试');
+Toast.warning('注意', '账号已存在');
+Toast.info('提示', '邮件已发送');
+```
+
 #### 重置密码流程
 
 AuthModal 支持完整的密码重置流程：
 
 1. **用户触发忘记密码**：在登录界面点击 "Forgot Password?" 链接
-2. **发送重置邮件**：输入邮箱后，系统发送带有 `verify_token` 的重置链接
-3. **自动唤起重置弹窗**：用户点击邮件中的链接返回网站时，AuthModal 会自动检测 URL 中的 `verify_token` 参数并显示重置密码表单
+2. **发送重置邮件**：输入邮箱后，系统发送带有 `reset_token` 的重置链接
+3. **自动唤起重置弹窗**：用户点击邮件中的链接返回网站时，AuthModal 会自动检测 URL 中的 `reset_token` 参数并显示重置密码表单
 4. **设置新密码**：用户输入并确认新密码后提交
-5. **自动清理 URL**：重置成功后自动清除 URL 中的 `verify_token` 参数
+5. **自动清理 URL**：重置成功后自动清除 URL 中的 `reset_token` 参数
 
 整个流程无需额外代码，AuthModal 会自动处理：
 
@@ -292,11 +330,11 @@ const authModal = new AuthModal({
 });
 
 // 2. 用户点击邮件中的重置链接后，AuthModal 会自动：
-//    - 检测 URL 中的 ?verify_token=xxx 参数
+//    - 检测 URL 中的 ?reset_token=xxx 参数
 //    - 显示重置密码表单
 //    - 用户提交新密码
 //    - 调用 client.resetPassword() API
-//    - 清理 URL 中的 verify_token 参数
+//    - 清理 URL 中的 reset_token 参数
 //    - 显示成功消息
 ```
 
@@ -454,7 +492,207 @@ await client.uninstallSkill({
 });
 ```
 
-### 7. 其他功能
+### 7. 邀请码管理
+
+```typescript
+// 列出我的邀请码
+const invites = await client.listInvites({
+  status: 'active',
+  page: 1,
+  page_size: 20,
+});
+console.log('我的邀请码:', invites.data.invites);
+
+// 获取邀请码统计
+const stats = await client.getInviteStats();
+console.log('总邀请码数:', stats.data.total_codes);
+console.log('活跃邀请码:', stats.data.active_codes);
+console.log('总使用次数:', stats.data.total_uses);
+
+// 获取邀请码详情
+const invite = await client.getInvite('inv_abc123');
+console.log('邀请码:', invite.data.code);
+console.log('已使用:', invite.data.used_count);
+console.log('最大使用次数:', invite.data.max_uses);
+
+// 获取邀请码使用记录
+const usages = await client.getInviteUsages('inv_abc123', {
+  page: 1,
+  page_size: 20,
+});
+console.log('使用记录:', usages.data.usages);
+```
+
+### 8. 邮箱验证与邀请码绑定
+
+#### 邮箱验证（自动登录）
+
+用户注册后会收到验证邮件，邮件中包含验证链接，格式为：`frontend_url?verify_token=xxx`
+
+**方式一：使用 AuthModal 自动处理（推荐）**
+
+```typescript
+import { AuthModal } from '@seaverse/auth-sdk';
+
+// 创建 AuthModal 实例
+const modal = new AuthModal({
+  client,
+  onLoginSuccess: (token, user) => {
+    localStorage.setItem('token', token);
+    console.log('邮箱验证并登录成功:', user);
+  },
+  onError: (error) => {
+    console.error('邮箱验证失败:', error);
+  }
+});
+
+// AuthModal 会自动检测 URL 中的 verify_token 参数
+// 检测到后会自动：
+// 1. 调用 verifyEmail() API 验证邮箱
+// 2. 获取返回的 JWT token 并自动登录
+// 3. 触发 onLoginSuccess 回调
+// 4. 清理 URL 中的 verify_token 参数
+// 5. 显示成功消息
+```
+
+**调试提示**：
+
+如果邮箱验证出现问题，请检查浏览器控制台日志：
+
+```javascript
+// 正常情况应该看到：
+[AuthModal] Detected verify_token, starting email verification...
+[AuthModal] Email verification successful: { id: "xxx", email: "user@example.com", ... }
+
+// 如果验证失败，会看到：
+[AuthModal] Email verification failed: Error: ...
+```
+
+**方式二：手动处理邮箱验证**
+
+```typescript
+// 验证邮箱（从邮件链接中获取 verify_token）
+const urlParams = new URLSearchParams(window.location.search);
+const verifyToken = urlParams.get('verify_token');
+
+if (verifyToken) {
+  const result = await client.verifyEmail(verifyToken);
+
+  // 自动登录：保存返回的 token
+  localStorage.setItem('token', result.data.token);
+  localStorage.setItem('refreshToken', result.data.refreshToken);
+
+  console.log('邮箱验证成功，已自动登录:', result.data.user);
+
+  // 重定向到主页
+  window.location.href = '/';
+}
+```
+
+#### 邀请码绑定（账户激活）
+
+当使用外部邮箱注册或 OAuth 登录但未提供邀请码时，会创建临时账户并需要后续绑定邀请码激活。后端会重定向到 `frontend_url?error_code=INVITE_CODE_REQUIRED&user_id=xxx&email=xxx`。
+
+**方式一：使用 AuthModal 自动处理（推荐）**
+
+```typescript
+import { AuthModal } from '@seaverse/auth-sdk';
+
+// 创建 AuthModal 实例
+const modal = new AuthModal({
+  client,
+  onLoginSuccess: (token, user) => {
+    localStorage.setItem('token', token);
+    console.log('登录成功:', user);
+  },
+  onInviteCodeRequired: (userId, email) => {
+    // 可选：当需要邀请码时的自定义处理
+    console.log('需要邀请码激活账户:', userId, email);
+  }
+});
+
+// AuthModal 会自动检测 URL 中的以下参数组合：
+// - error_code=INVITE_CODE_REQUIRED
+// - user_id 或 temp_user_id（用户ID）
+// - email（可选，用户邮箱）
+//
+// 检测到后会自动：
+// 1. 显示邀请码输入界面
+// 2. 用户输入邀请码后调用 bindInviteCode() API
+// 3. 激活成功后自动登录（保存 token）
+// 4. 清理 URL 中的参数
+```
+
+**调试提示**：
+
+如果邀请码弹窗没有出现，请检查浏览器控制台是否有以下日志：
+
+```javascript
+// 正常情况应该看到：
+[AuthModal] Detected INVITE_CODE_REQUIRED: {
+  errorCode: "INVITE_CODE_REQUIRED",
+  userId: "xxx",
+  tempUserId: null,
+  email: "user@example.com",
+  fullURL: "http://localhost:8001/?error_code=INVITE_CODE_REQUIRED&user_id=xxx&email=xxx"
+}
+
+// 如果 user_id 缺失，会看到错误提示：
+[AuthModal] Missing user_id in URL parameters.
+// 并弹出 alert 显示完整 URL，方便排查后端重定向问题
+```
+
+**方式二：手动处理邀请码绑定**
+
+```typescript
+// 1. 检查 URL 中是否需要邀请码
+const urlParams = new URLSearchParams(window.location.search);
+const errorCode = urlParams.get('error_code');
+const userId = urlParams.get('user_id');
+
+if (errorCode === 'INVITE_CODE_REQUIRED' && userId) {
+  // 2. 显示邀请码输入界面（自定义 UI）
+  const inviteCode = await showInviteCodeInput(); // 你的自定义UI
+
+  // 3. 绑定邀请码
+  const result = await client.bindInviteCode({
+    user_id: userId,
+    invite_code: inviteCode
+  });
+
+  // 4. 激活成功，自动登录
+  localStorage.setItem('token', result.data.token);
+  localStorage.setItem('refreshToken', result.data.refreshToken);
+  console.log('账户激活成功:', result.data.user);
+
+  // 5. 重定向到主页
+  window.location.href = '/';
+}
+```
+
+**方式三：使用静态方法处理**
+
+```typescript
+import { AuthModal } from '@seaverse/auth-sdk';
+
+// AuthModal 提供静态方法处理邀请码场景
+const inviteCodeInfo = AuthModal.handleInviteCodeRequired(
+  { client },
+  (userId, email) => {
+    // 自定义处理逻辑
+    const code = prompt(`请输入邀请码激活账户 (${email}):`);
+    if (code) {
+      client.bindInviteCode({ user_id: userId, invite_code: code })
+        .then(res => {
+          localStorage.setItem('token', res.data.token);
+          window.location.reload();
+        });
+    }
+  }
+);
+```
+
+### 9. 其他功能
 
 ```typescript
 // 获取API Service Token
@@ -526,6 +764,105 @@ const client = new SeaVerseBackendAPIClient({
 });
 ```
 
+### 请求重试配置
+
+SDK 支持自定义 HTTP 请求重试策略。**默认情况下重试功能是禁用的（maxRetries: 0）**，以确保请求的可预测性。
+
+#### 默认行为（禁用重试）
+
+```typescript
+const client = new SeaVerseBackendAPIClient({
+  appId: 'your app id',
+  // retryOptions 未设置，默认不重试
+});
+
+// 如果请求失败，会立即返回错误，不会重试
+```
+
+#### 启用基础重试
+
+```typescript
+import { SeaVerseBackendAPIClient } from '@seaverse/auth-sdk';
+
+const client = new SeaVerseBackendAPIClient({
+  appId: 'your app id',
+  retryOptions: {
+    maxRetries: 3,        // 最多重试 3 次
+    retryDelay: 1000,     // 初始延迟 1000ms (1秒)
+    // 默认会对以下状态码重试：[408, 429, 500, 502, 503, 504]
+  },
+});
+```
+
+**重试策略说明**：
+- 采用**指数退避**算法：第1次等待1秒，第2次等待2秒，第3次等待4秒
+- 自动重试的 HTTP 状态码：
+  - `408` - Request Timeout（请求超时）
+  - `429` - Too Many Requests（限流）
+  - `500` - Internal Server Error（服务器内部错误）
+  - `502` - Bad Gateway（网关错误）
+  - `503` - Service Unavailable（服务不可用）
+  - `504` - Gateway Timeout（网关超时）
+- 网络错误（无响应）也会触发重试
+
+#### 自定义重试状态码
+
+```typescript
+const client = new SeaVerseBackendAPIClient({
+  appId: 'your app id',
+  retryOptions: {
+    maxRetries: 5,
+    retryDelay: 2000,
+    retryStatusCodes: [503, 504],  // 只对 503 和 504 重试
+  },
+});
+```
+
+#### 自定义重试逻辑
+
+```typescript
+import type { RetryOptions } from '@seaverse/auth-sdk';
+
+const retryOptions: RetryOptions = {
+  maxRetries: 3,
+  retryDelay: 1000,
+  // 自定义判断逻辑：只对特定错误重试
+  shouldRetry: (error) => {
+    // 只对服务不可用错误重试
+    if (error.response?.status === 503) {
+      return true;
+    }
+    // 对没有响应的网络错误重试
+    if (!error.response) {
+      return true;
+    }
+    return false;
+  },
+};
+
+const client = new SeaVerseBackendAPIClient({
+  appId: 'your app id',
+  retryOptions,
+});
+```
+
+#### RetryOptions 类型定义
+
+```typescript
+interface RetryOptions {
+  maxRetries?: number;           // 最大重试次数，默认 0（禁用）
+  retryDelay?: number;           // 初始重试延迟（毫秒），默认 1000
+  retryStatusCodes?: number[];   // 触发重试的状态码列表
+  shouldRetry?: (error: AxiosError) => boolean;  // 自定义重试判断函数
+}
+```
+
+**使用建议**：
+- ⚠️ **生产环境建议禁用重试**（默认行为），避免在业务逻辑错误时产生重复请求
+- ✅ 仅在网络不稳定的场景启用重试，如移动端应用、弱网环境
+- ✅ 确保后端 API 支持幂等性操作，避免重试导致的副作用
+- ✅ 对于关键业务（如支付），建议使用自定义 `shouldRetry` 仔细控制重试逻辑
+
 ### 环境配置
 
 SDK支持以下环境：
@@ -550,14 +887,53 @@ SDK支持以下环境：
 | 方法 | 参数 | 返回值 | 说明 |
 |------|------|--------|------|
 | `register()` | `{ email, password, username?, invitation_code?, frontend_url? }` | `RegisterResponse` | 注册新用户，frontend_url 为邮箱验证链接的前端URL，默认为 window.location.origin |
-| `login()` | `{ email, password }` | `LoginResponse` | 用户登录 |
+| `login()` | `{ email, password, frontend_url? }` | `LoginResponse` | 用户登录，frontend_url 用于未验证邮箱时发送验证邮件，默认为 https://seaverse.ai/ |
 | `getCurrentUser()` | - | `User` | 获取当前用户 |
 | `logout()` | - | `SuccessResponse` | 登出 |
+| `verifyEmail()` | `verifyToken: string` | `EmailVerificationResponse` | 验证邮箱并返回自动登录 token |
+| `bindInviteCode()` | `{ user_id, invite_code }` | `BindInviteCodeResponse` | 绑定邀请码激活临时账户并自动登录 |
 | `forgotPassword()` | `{ email, frontend_url? }` | `SuccessResponse` | 忘记密码，frontend_url 默认为 window.location.origin |
 | `resetPassword()` | `{ token, new_password }` | `SuccessResponse` | 重置密码 |
 | `setToken()` | `token: string` | `void` | 设置认证 token（OAuth 登录后使用） |
 | `getApiServiceToken()` | - | `ApiServiceTokenResponse` | 获取API Token |
 
+#### 注册流程说明
+
+`register()` 方法支持三种注册流程，SDK 会根据后端响应自动处理：
+
+**流程 1: 立即激活（默认）**
+```typescript
+const response = await client.register({ email, password });
+// response.success === true
+// response.requiresEmailVerification === undefined (或 false)
+// response.requiresInvitationCode === undefined (或 false)
+// → SDK 自动调用 login() 并触发 onSignupSuccess 回调
+```
+
+**流程 2: 需要邮箱验证**
+```typescript
+const response = await client.register({ email, password });
+// response.success === true
+// response.requiresEmailVerification === true
+// → SDK 显示 Toast 提示用户检查邮箱
+// → 不会自动调用 login()，用户需要点击邮件中的验证链接
+```
+
+**流程 3: 需要邀请码激活**
+```typescript
+const response = await client.register({ email, password });
+// response.success === true
+// response.requiresInvitationCode === true
+// response.tempUserId === "temp_xxx"
+// → SDK 显示邀请码输入表单
+// → 不会自动调用 login()，用户需要输入邀请码
+```
+
+**重要提示**：
+- AuthModal 会自动处理这三种流程，无需手动判断
+- 只有在无需验证或激活的情况下，才会自动调用 `login()`
+- 这避免了在邮箱未验证或账户未激活时产生不必要的登录请求
+
 ### OAuth相关
 
 | 方法 | 参数 | 返回值 | 说明 |
@@ -590,6 +966,15 @@ SDK支持以下环境：
 | `listUserSkills()` | - | `UserInstalledSkillsListResponse` | 列出已安装技能 |
 | `uninstallSkill()` | `{ skillId }` | `SuccessResponse` | 卸载技能 |
 
+### 邀请码管理
+
+| 方法 | 参数 | 返回值 | 说明 |
+|------|------|--------|------|
+| `listInvites()` | `{ page?, page_size?, status? }` | `ListInvitesResponse` | 列出我的邀请码 |
+| `getInviteStats()` | - | `InviteStatsResponse` | 获取邀请码统计 |
+| `getInvite()` | `inviteId: string` | `InviteCodeDetailResponse` | 获取邀请码详情 |
+| `getInviteUsages()` | `inviteId: string, { page?, page_size? }` | `ListInviteUsagesResponse` | 获取邀请码使用记录 |
+
 ### 其他
 
 | 方法 | 参数 | 返回值 | 说明 |
@@ -598,6 +983,74 @@ SDK支持以下环境：
 | `getConversationStatus()` | `{ conversationId }` | `ConversationStatusResponse` | 获取对话状态 |
 | `getSpeechToken()` | - | `SpeechTokenResponse` | 获取语音Token |
 
+## 响应格式兼容性
+
+### 自动响应解包
+
+从 v0.2.5 开始，SDK 自动兼容两种API响应格式，无需手动处理：
+
+**格式 1: 包装格式**（推荐）
+```json
+{
+  "data": {
+    "token": "eyJhbGc...",
+    "user": { ... }
+  },
+  "success": true
+}
+```
+
+**格式 2: 扁平格式**（向后兼容）
+```json
+{
+  "token": "eyJhbGc...",
+  "user": { ... }
+}
+```
+
+SDK 会自动检测响应格式并提取正确的数据：
+
+```typescript
+// 无论后端返回哪种格式，以下代码都能正常工作
+const loginResult = await client.login({
+  email: 'user@example.com',
+  password: 'password123',
+});
+
+console.log(loginResult.token); // ✅ 始终能正确获取 token
+console.log(loginResult.user);  // ✅ 始终能正确获取 user
+```
+
+### 受影响的方法
+
+以下方法已实现自动响应解包：
+
+- ✅ `login()` - 登录接口
+- ✅ `register()` - 注册接口
+- ✅ `getCurrentUser()` - 获取当前用户
+
+### 实现原理
+
+SDK 内部通过以下逻辑自动处理响应格式：
+
+```typescript
+const response = await httpClient.request(config);
+const responseData = response.data;
+
+// 检测并解包
+if (responseData.data && typeof responseData.data === 'object') {
+  // 包装格式: 提取 data 字段
+  return responseData.data;
+}
+// 扁平格式: 直接返回
+return responseData;
+```
+
+这意味着：
+- 🔄 **后端格式变更无需前端修改** - 后端可以自由调整响应格式
+- 🔧 **渐进式迁移** - 可以逐步将不同接口迁移到新格式
+- ✅ **向后兼容** - 旧代码无需修改即可继续工作
+
 ## 错误处理
 
 ### 错误响应格式
@@ -846,8 +1299,17 @@ interface LoginResponse {
 // 注册响应
 interface RegisterResponse {
   success: boolean;
-  message: string;
-  userId: string;
+  message?: string;
+  userId?: string;
+  // 邮箱验证相关
+  requiresEmailVerification?: boolean;  // 是否需要邮箱验证
+  // 邀请码激活相关
+  requiresInvitationCode?: boolean;     // 是否需要邀请码激活
+  tempUserId?: string;                  // 临时用户ID（需要激活）
+  // 错误信息
+  error?: string;
+  code?: string;                        // 如 'ACCOUNT_EXISTS'
+  details?: Record<string, any>;
 }
 
 // AuthModal选项
@@ -856,6 +1318,7 @@ interface AuthModalOptions {
   theme?: 'dark' | 'light';
   onLoginSuccess?: (token: string, user: any) => void;
   onSignupSuccess?: (token: string, user: any) => void;
+  onInviteCodeRequired?: (userId: string, email: string) => void; // 当需要邀请码激活时的回调
   onError?: (error: Error) => void;
   returnUrl?: string;        // OAuth 登录后返回的 URL，可选，默认为 window.location.origin
   enableOAuth?: {
@@ -1033,7 +1496,14 @@ MIT © [SeaVerse Team](mailto:support@seaverse.com)
 
 ## 更新日志
 
-### v0.2.0 (当前版本)
+### v0.2.5 (当前版本)
+- 🔄 **响应格式兼容**: 自动兼容包装格式和扁平格式的API响应
+  - 修复登录时提示 "Invalid response from server" 的问题
+  - `login()`, `register()`, `getCurrentUser()` 方法自动解包 `data` 字段
+  - 支持两种格式: `{ data: {...}, success: true }` 和 `{ ... }`
+- 📝 **文档更新**: 新增响应格式兼容性章节
+
+### v0.2.0
 - 🔄 **API路径更新**: 所有认证API从 `/api/auth/*` 迁移到 `/sdk/v1/auth/*`
 - 🏢 **多租户支持**: User模型新增 `app_id` 字段，支持多应用隔离
 - 🔑 **重要变更**: `appId` 现在是**必需参数**，SDK 自动在所有请求中添加 `X-App-ID` 请求头