@seaverse/auth-sdk 0.2.1 → 0.2.3

package/README.md

@@ -96,6 +96,14 @@ const registerResult = await client.register({
   invitation_code: 'INVITE123',     // 可选
 });
 
+// 检查注册结果
+if (registerResult.success) {
+  console.log('注册成功:', registerResult);
+} else if (registerResult.code === 'ACCOUNT_EXISTS') {
+  console.log('账户已存在，请直接登录');
+  console.log('错误详情:', registerResult.details);
+}
+
 // 登录
 const loginResult = await client.login({
   email: 'user@example.com',
@@ -126,44 +134,73 @@ await client.resetPassword({
 });
 ```
 
-### 3. OAuth 第三方登录
+### 3. OAuth 第三方登录 (Backend Proxy Mode)
+
+SDK 使用 Backend Proxy Mode，Client Secret 永不暴露给前端，安全性更高。
+
+**优势**:
+- ✅ Client Secret 从不暴露给前端
+- ✅ 支持任意开发者域名(无需在 OAuth 平台配置)
+- ✅ 内置 CSRF 防护
+- ✅ 零配置，开箱即用
 
-#### Google 登录
+**工作流程**:
+1. 前端调用 `{provider}Authorize()` 获取 OAuth URL
+2. 前端重定向用户到 OAuth 提供商
+3. 用户授权后，OAuth 提供商回调到固定的 account-hub URL
+4. account-hub 处理 OAuth，创建 JWT token
+5. account-hub 302 重定向到 `return_url?token=xxx`
+6. 前端从 URL 提取 token 并存储
+
+#### 使用示例
+
+**方式1：使用默认 return_url（当前页面）**
 
 ```typescript
-// 步骤1: 获取Google授权码后，交换token
-const result = await client.googleCodeToToken({
-  code: 'google-auth-code',
-  redirectUri: 'https://yourdomain.com/auth/callback',
-});
+// Google 登录
+const { authorize_url } = await client.googleAuthorize();
+window.location.href = authorize_url;
 
-localStorage.setItem('token', result.token);
+// Discord 登录
+const { authorize_url } = await client.discordAuthorize();
+window.location.href = authorize_url;
 
-// 解绑Google账号
-await client.unlinkGoogle();
+// GitHub 登录
+const { authorize_url } = await client.githubAuthorize();
+window.location.href = authorize_url;
 ```
 
-#### Discord 登录
+**方式2：自定义 return_url**
 
 ```typescript
-const result = await client.discordCodeToToken({
-  code: 'discord-auth-code',
-  redirectUri: 'https://yourdomain.com/auth/callback',
+// 登录后跳转到 dashboard
+const { authorize_url } = await client.googleAuthorize({
+  return_url: 'https://mygame.com/dashboard'
 });
+window.location.href = authorize_url;
+```
 
-// 解绑Discord账号
-await client.unlinkDiscord();
+**在回调页面提取 token**:
+
+```typescript
+// URL: https://mygame.com/?token=eyJhbGc...
+const token = new URLSearchParams(window.location.search).get('token');
+if (token) {
+  localStorage.setItem('token', token);
+  // 登录成功，跳转或更新 UI
+}
 ```
 
-#### GitHub 登录
+#### OAuth 账号解绑
 
 ```typescript
-const result = await client.githubCodeToToken({
-  code: 'github-auth-code',
-  redirectUri: 'https://yourdomain.com/auth/callback',
-});
+// 解绑 Google 账号
+await client.unlinkGoogle();
+
+// 解绑 Discord 账号
+await client.unlinkDiscord();
 
-// 解绑GitHub账号
+// 解绑 GitHub 账号
 await client.unlinkGithub();
 ```
 
@@ -189,7 +226,7 @@ const client = new SeaVerseBackendAPIClient({
   environment: 'production',
 });
 
-// 创建登录弹窗（深色主题）
+// 创建登录弹窗
 const authModal = new AuthModal({
   client,
   theme: 'dark', // 'dark' | 'light' - 默认为 'dark'
@@ -211,20 +248,12 @@ const authModal = new AuthModal({
     console.error('认证错误:', error.message);
   },
 
-  // OAuth配置（可选）
-  oauthConfig: {
-    google: {
-      clientId: 'YOUR_GOOGLE_CLIENT_ID',          // 必填
-      redirectUri: window.location.origin,        // 可选，默认为 window.location.origin
-    },
-    discord: {
-      clientId: 'YOUR_DISCORD_CLIENT_ID',         // 必填
-      redirectUri: window.location.origin,        // 可选，默认为 window.location.origin
-    },
-    github: {
-      clientId: 'YOUR_GITHUB_CLIENT_ID',          // 必填
-      redirectUri: window.location.origin,        // 可选，默认为 window.location.origin
-    },
+  // OAuth 配置（可选）
+  returnUrl: 'https://mygame.com/',  // OAuth 登录后返回的 URL，可选，默认为 window.location.origin
+  enableOAuth: {
+    google: true,   // 启用 Google 登录
+    discord: true,  // 启用 Discord 登录
+    github: true,   // 启用 GitHub 登录
   },
 });
 
@@ -239,64 +268,98 @@ authModal.hide();
 
 // 销毁弹窗
 authModal.destroy();
+```
+
 #### OAuth 配置说明
 
-`oauthConfig` 参数是**完全可选的**：
+`enableOAuth` 参数是**完全可选的**：
 
-- 如果**不提供** `oauthConfig`，则不会显示任何第三方登录按钮
-- 如果**部分配置**（如只配置 Google），则只显示已配置的按钮
+- 如果**不提供** `enableOAuth`，则不会显示任何第三方登录按钮
+- 如果**部分配置**（如只启用 Google），则只显示已启用的按钮
 - 如果**完整配置**所有平台，则显示所有第三方登录按钮
 
 **配置字段说明**：
-- `clientId`：**必填** - OAuth 应用的客户端 ID
-- `redirectUri`：**可选** - OAuth 回调地址，不填则默认为 `window.location.origin`
-- `scope`：**可选** - OAuth 权限范围，每个平台有默认值
+- `returnUrl`：**可选** - OAuth 登录后返回的 URL，不填则默认为 `window.location.origin`
+- `enableOAuth.google`：是否启用 Google 登录
+- `enableOAuth.discord`：是否启用 Discord 登录
+- `enableOAuth.github`：是否启用 GitHub 登录
 
 ```typescript
 // 示例1：无OAuth按钮
-const client1 = new SeaVerseBackendAPIClient({ appId: 'your app id' });
 const authModal1 = new AuthModal({
-  client: client1,
+  client,
   theme: 'dark',
-  // 不传 oauthConfig，不显示任何OAuth按钮
+  // 不传 enableOAuth，不显示任何OAuth按钮
 });
 
 // 示例2：只显示Google登录
-const client2 = new SeaVerseBackendAPIClient({ appId: 'your app id' });
 const authModal2 = new AuthModal({
-  client: client2,
+  client,
   theme: 'light',
-  oauthConfig: {
-    google: {
-      clientId: 'YOUR_GOOGLE_CLIENT_ID',
-      // redirectUri 可选，不填则默认为 window.location.origin
-    },
-    // Discord 和 GitHub 未配置，不会显示这些按钮
+  returnUrl: 'https://mygame.com/dashboard',
+  enableOAuth: {
+    google: true,
+    // Discord 和 GitHub 未启用，不会显示这些按钮
   },
 });
 
-// 示例3：显示所有OAuth按钮（自定义 redirectUri）
-const client3 = new SeaVerseBackendAPIClient({ appId: 'your app id' });
+// 示例3：显示所有OAuth按钮
 const authModal3 = new AuthModal({
-  client: client3,
+  client,
   theme: 'dark',
-  oauthConfig: {
-    google: {
-      clientId: '...',
-      redirectUri: 'https://yourdomain.com/auth/callback' // 自定义回调地址
-    },
-    discord: {
-      clientId: '...'
-      // redirectUri 可选，不填则默认为 window.location.origin
-    },
-    github: {
-      clientId: '...'
-      // redirectUri 可选，不填则默认为 window.location.origin
-    },
+  enableOAuth: {
+    google: true,
+    discord: true,
+    github: true,
   },
 });
 ```
 
+#### 处理 OAuth 回调
+
+在 Backend Proxy Mode 下，OAuth 登录后会重定向到 `returnUrl?token=xxx`。在页面加载时检查并处理token:
+
+```typescript
+// 在页面加载时自动处理 OAuth 回调
+const result = AuthModal.handleOAuthCallback({
+  client,
+  onLoginSuccess: (token) => {
+    localStorage.setItem('token', token);
+    console.log('OAuth 登录成功');
+
+    // 现在可以直接调用需要认证的接口
+    // handleOAuthCallback 已自动调用 client.setToken()
+    client.getCurrentUser()
+      .then(user => console.log('用户信息:', user));
+  },
+});
+
+if (result) {
+  console.log('处理了 OAuth 回调，token:', result.token);
+}
+```
+
+**重要说明**：
+- `handleOAuthCallback()` 会自动调用 `client.setToken(token)` 来更新 client 的认证配置
+- 这意味着在 `onLoginSuccess` 回调之后，所有需要认证的 API（如 `getCurrentUser()`、`logout()` 等）都会自动带上 `Authorization` header
+
+#### 手动设置 Token
+
+如果你不使用 `AuthModal.handleOAuthCallback()`，也可以手动设置 token：
+
+```typescript
+// 从 URL 提取 token
+const token = new URLSearchParams(window.location.search).get('token');
+if (token) {
+  // 手动设置 token
+  client.setToken(token);
+  localStorage.setItem('token', token);
+
+  // 现在可以调用需要认证的接口
+  const user = await client.getCurrentUser();
+}
+```
+
 ### 5. 容器管理
 
 ```typescript
@@ -462,15 +525,16 @@ SDK支持以下环境：
 | `logout()` | - | `SuccessResponse` | 登出 |
 | `forgotPassword()` | `{ email }` | `SuccessResponse` | 忘记密码 |
 | `resetPassword()` | `{ token, new_password }` | `SuccessResponse` | 重置密码 |
+| `setToken()` | `token: string` | `void` | 设置认证 token（OAuth 登录后使用） |
 | `getApiServiceToken()` | - | `ApiServiceTokenResponse` | 获取API Token |
 
 ### OAuth相关
 
 | 方法 | 参数 | 返回值 | 说明 |
 |------|------|--------|------|
-| `googleCodeToToken()` | `{ code, redirectUri }` | `OAuthTokenResponse` | Google登录 |
-| `discordCodeToToken()` | `{ code, redirectUri }` | `OAuthTokenResponse` | Discord登录 |
-| `githubCodeToToken()` | `{ code, redirectUri }` | `OAuthTokenResponse` | GitHub登录 |
+| `googleAuthorize()` | `{ return_url? }` | `OAuthAuthorizeResponse` | Google OAuth 授权 URL |
+| `discordAuthorize()` | `{ return_url? }` | `OAuthAuthorizeResponse` | Discord OAuth 授权 URL |
+| `githubAuthorize()` | `{ return_url? }` | `OAuthAuthorizeResponse` | GitHub OAuth 授权 URL |
 | `unlinkGoogle()` | - | `SuccessResponse` | 解绑Google |
 | `unlinkDiscord()` | - | `SuccessResponse` | 解绑Discord |
 | `unlinkGithub()` | - | `SuccessResponse` | 解绑GitHub |
@@ -504,6 +568,222 @@ SDK支持以下环境：
 | `getConversationStatus()` | `{ conversationId }` | `ConversationStatusResponse` | 获取对话状态 |
 | `getSpeechToken()` | - | `SpeechTokenResponse` | 获取语音Token |
 
+## 错误处理
+
+### 错误响应格式
+
+所有 API 错误都遵循统一的响应格式:
+
+```typescript
+interface ApiError {
+  success: false;           // 错误时始终为 false
+  error: string;            // 人类可读的错误消息
+  code?: string;            // 机器可读的错误码
+  details?: any;            // 额外的错误详情
+}
+```
+
+### 错误码
+
+SDK 提供了标准的错误码枚举:
+
+```typescript
+import { ErrorCode } from '@seaverse/auth-sdk';
+
+// 账户相关错误
+ErrorCode.ACCOUNT_EXISTS         // 账户已存在
+ErrorCode.ACCOUNT_NOT_FOUND      // 账户不存在
+ErrorCode.ACCOUNT_SUSPENDED      // 账户已被暂停
+ErrorCode.INVALID_CREDENTIALS    // 登录凭证无效
+ErrorCode.EMAIL_NOT_VERIFIED     // 邮箱未验证
+
+// 验证相关错误
+ErrorCode.INVALID_EMAIL          // 无效的邮箱地址
+ErrorCode.INVALID_PASSWORD       // 无效的密码
+ErrorCode.PASSWORD_TOO_WEAK      // 密码强度不够
+
+// 邀请码相关错误
+ErrorCode.INVALID_INVITATION_CODE // 无效的邀请码
+ErrorCode.INVITATION_REQUIRED     // 需要邀请码
+
+// Token 相关错误
+ErrorCode.INVALID_TOKEN          // 无效的 token
+ErrorCode.TOKEN_EXPIRED          // Token 已过期
+
+// 内部错误
+ErrorCode.INTERNAL_ERROR         // 服务器内部错误
+```
+
+### 错误处理最佳实践
+
+#### 1. 注册时处理重复用户
+
+由于后端在账户已存在时返回 200 OK（成功响应），所以前端不会抛出异常，而是在响应体中包含错误信息。
+
+```typescript
+import { ErrorCode } from '@seaverse/auth-sdk';
+
+const result = await client.register({
+  email: 'user@example.com',
+  password: 'password123',
+});
+
+// 检查响应中的 success 字段
+if (result.success) {
+  console.log('注册成功:', result);
+  // 进行后续操作，如自动登录
+} else if (result.code === ErrorCode.ACCOUNT_EXISTS) {
+  // 账户已存在，提示用户
+  const { email, app_id } = result.details;
+  console.log(`账户 ${email} 已存在于应用 ${app_id} 中`);
+
+  // 显示友好的提示信息
+  alert('This email is already registered. Please login instead.');
+
+  // 或者引导用户去登录
+  showLoginModal();
+} else {
+  // 处理其他错误
+  console.error('注册失败:', result.error);
+}
+```
+
+#### 2. 登录时处理各种错误
+
+```typescript
+try {
+  const result = await client.login({
+    email: 'user@example.com',
+    password: 'wrong-password',
+  });
+  console.log('登录成功:', result);
+} catch (error) {
+  const errorCode = error.response?.data?.code;
+
+  switch (errorCode) {
+    case ErrorCode.INVALID_CREDENTIALS:
+      showError('用户名或密码错误');
+      break;
+    case ErrorCode.EMAIL_NOT_VERIFIED:
+      showError('请先验证您的邮箱');
+      showResendVerificationButton();
+      break;
+    case ErrorCode.ACCOUNT_SUSPENDED:
+      showError('您的账户已被暂停，请联系管理员');
+      break;
+    default:
+      showError('登录失败，请稍后重试');
+  }
+}
+```
+
+#### 3. 通用错误处理函数
+
+```typescript
+import { ErrorCode } from '@seaverse/auth-sdk';
+
+function handleApiError(error: any) {
+  const apiError = error.response?.data;
+
+  if (!apiError) {
+    // 网络错误或其他未知错误
+    return {
+      title: '网络错误',
+      message: '请检查您的网络连接',
+    };
+  }
+
+  // 根据错误码返回用户友好的消息
+  const errorMessages: Record<string, { title: string; message: string }> = {
+    [ErrorCode.ACCOUNT_EXISTS]: {
+      title: '账户已存在',
+      message: '该邮箱已注册，请直接登录',
+    },
+    [ErrorCode.INVALID_CREDENTIALS]: {
+      title: '登录失败',
+      message: '用户名或密码错误',
+    },
+    [ErrorCode.EMAIL_NOT_VERIFIED]: {
+      title: '邮箱未验证',
+      message: '请先验证您的邮箱地址',
+    },
+    [ErrorCode.INVALID_INVITATION_CODE]: {
+      title: '邀请码无效',
+      message: '请检查您的邀请码是否正确',
+    },
+    [ErrorCode.TOKEN_EXPIRED]: {
+      title: '登录已过期',
+      message: '请重新登录',
+    },
+  };
+
+  return errorMessages[apiError.code] || {
+    title: '操作失败',
+    message: apiError.error || '发生未知错误',
+  };
+}
+
+// 使用示例
+try {
+  await client.register({ email, password });
+} catch (error) {
+  const { title, message } = handleApiError(error);
+  showNotification(title, message);
+}
+```
+
+#### 4. TypeScript 类型安全的错误处理
+
+```typescript
+import { ErrorCode, models } from '@seaverse/auth-sdk';
+
+async function safeRegister(email: string, password: string) {
+  // Register API now returns 200 OK for both success and account exists cases
+  const result = await client.register({ email, password });
+
+  if (result.success) {
+    return {
+      success: true,
+      data: result,
+    };
+  } else if (result.code === ErrorCode.ACCOUNT_EXISTS) {
+    // TypeScript knows the type of details
+    const details = result.details as models.AccountExistsErrorDetails;
+    return {
+      success: false,
+      error: 'ACCOUNT_EXISTS',
+      email: details.email,
+      appId: details.app_id,
+    };
+  } else {
+    return {
+      success: false,
+      error: result.error || 'Unknown error',
+    };
+  }
+}
+
+// Usage
+const registerResult = await safeRegister('user@example.com', 'password123');
+if (registerResult.success) {
+  console.log('Registration successful');
+} else if (registerResult.error === 'ACCOUNT_EXISTS') {
+  console.log(`Account already exists: ${registerResult.email}`);
+}
+```
+
+### HTTP 状态码对照
+
+| HTTP状态码 | 错误码示例 | 说明 |
+|-----------|----------|------|
+| 200 OK | `ACCOUNT_EXISTS` | 账户已存在（业务错误但返回成功响应） |
+| 400 Bad Request | `INVALID_EMAIL`, `PASSWORD_TOO_WEAK` | 请求参数无效 |
+| 401 Unauthorized | `INVALID_CREDENTIALS`, `TOKEN_EXPIRED` | 认证失败 |
+| 403 Forbidden | `EMAIL_NOT_VERIFIED`, `ACCOUNT_SUSPENDED` | 权限不足 |
+| 500 Internal Server Error | `INTERNAL_ERROR` | 服务器内部错误 |
+
+**注意**：对于注册接口，账户已存在的情况会返回 200 OK，但在响应体中 `success: false` 和 `code: "ACCOUNT_EXISTS"`。这样设计是为了前端能够更容易地处理这种常见的业务场景。
+
 ## 类型定义
 
 ```typescript
@@ -547,25 +827,11 @@ interface AuthModalOptions {
   onLoginSuccess?: (token: string, user: any) => void;
   onSignupSuccess?: (token: string, user: any) => void;
   onError?: (error: Error) => void;
-  oauthConfig?: OAuthConfig;
-}
-
-// OAuth配置
-interface OAuthConfig {
-  google?: {
-    clientId: string;        // 必填
-    redirectUri?: string;    // 可选，默认为 window.location.origin
-    scope?: string;          // 可选，默认为 'openid email profile'
-  };
-  discord?: {
-    clientId: string;        // 必填
-    redirectUri?: string;    // 可选，默认为 window.location.origin
-    scope?: string;          // 可选，默认为 'identify email'
-  };
-  github?: {
-    clientId: string;        // 必填
-    redirectUri?: string;    // 可选，默认为 window.location.origin
-    scope?: string;          // 可选，默认为 'read:user user:email'
+  returnUrl?: string;        // OAuth 登录后返回的 URL，可选，默认为 window.location.origin
+  enableOAuth?: {
+    google?: boolean;        // 启用 Google 登录
+    discord?: boolean;       // 启用 Discord 登录
+    github?: boolean;        // 启用 GitHub 登录
   };
 }
 ```