@seaverse/auth-sdk 0.2.2 → 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',
@@ -560,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

package/dist/index.cjs

@@ -1136,9 +1136,37 @@ function resolveBaseURL(options) {
  * Type definitions for SeaVerse Dispatcher API
  * Generated from auth.yaml OpenAPI specification
  */
+// ============================================================================
+// Error Types
+// ============================================================================
+/**
+ * Error codes for authentication system
+ */
+exports.ErrorCode = void 0;
+(function (ErrorCode) {
+    // Account errors
+    ErrorCode["ACCOUNT_EXISTS"] = "ACCOUNT_EXISTS";
+    ErrorCode["ACCOUNT_NOT_FOUND"] = "ACCOUNT_NOT_FOUND";
+    ErrorCode["ACCOUNT_SUSPENDED"] = "ACCOUNT_SUSPENDED";
+    ErrorCode["INVALID_CREDENTIALS"] = "INVALID_CREDENTIALS";
+    ErrorCode["EMAIL_NOT_VERIFIED"] = "EMAIL_NOT_VERIFIED";
+    // Validation errors
+    ErrorCode["INVALID_EMAIL"] = "INVALID_EMAIL";
+    ErrorCode["INVALID_PASSWORD"] = "INVALID_PASSWORD";
+    ErrorCode["PASSWORD_TOO_WEAK"] = "PASSWORD_TOO_WEAK";
+    // Invitation errors
+    ErrorCode["INVALID_INVITATION_CODE"] = "INVALID_INVITATION_CODE";
+    ErrorCode["INVITATION_REQUIRED"] = "INVITATION_REQUIRED";
+    // Token errors
+    ErrorCode["INVALID_TOKEN"] = "INVALID_TOKEN";
+    ErrorCode["TOKEN_EXPIRED"] = "TOKEN_EXPIRED";
+    // Internal errors
+    ErrorCode["INTERNAL_ERROR"] = "INTERNAL_ERROR";
+})(exports.ErrorCode || (exports.ErrorCode = {}));
 
 var models = /*#__PURE__*/Object.freeze({
-    __proto__: null
+    __proto__: null,
+    get ErrorCode () { return exports.ErrorCode; }
 });
 
 /**
@@ -2444,13 +2472,22 @@ class AuthModal {
                     this.showMessage('Account Created', response.message || 'Your account has been created successfully!');
                 }
             }
+            else if (response.code === exports.ErrorCode.ACCOUNT_EXISTS) {
+                // Handle account already exists error
+                this.showMessage('Account Already Exists', 'This email is already registered. Please login instead.');
+            }
             else {
-                throw new Error('Registration failed');
+                throw new Error(response.error || 'Registration failed');
             }
         }
         catch (error) {
-            // Handle error
-            const errorMessage = error instanceof Error ? error.message : 'Signup failed';
+            // Handle HTTP errors
+            if (error.response?.data?.code === exports.ErrorCode.ACCOUNT_EXISTS) {
+                this.showMessage('Account Already Exists', 'This email is already registered. Please login instead.');
+                return;
+            }
+            // Handle other errors
+            const errorMessage = error.response?.data?.error || error.message || 'Signup failed';
             this.showError(errorMessage);
             if (this.options.onError) {
                 this.options.onError(error);
@@ -2473,8 +2510,8 @@ class AuthModal {
         try {
             // Show loading state
             submitBtn.disabled = true;
-            // TODO: Call forgot password API when available
-            // await this.client.postapiauthforgotpassword({ email });
+            // Call forgot password API
+            await this.client.forgotPassword({ email });
             // Show success message
             this.showMessage('Reset Link Sent', `We've sent a password reset link to ${email}`);
         }