@seaverse/auth-sdk 0.1.5 → 0.2.1

package/README.md

@@ -1,103 +1,230 @@
-# @seaverseai/auth-sdk
+# @seaverse/auth-sdk
 
-SeaVerse 认证 SDK - 提供完整的用户认证功能和精美的登录注册 UI 组件
+SeaVerse Backend API 客户端 SDK - 提供完整的认证、容器管理、技能市场等功能
 
-[![npm version](https://img.shields.io/npm/v/@seaverseai/auth-sdk.svg)](https://www.npmjs.com/package/@seaverseai/auth-sdk)
+[![npm version](https://img.shields.io/npm/v/@seaverse/auth-sdk.svg)](https://www.npmjs.com/package/@seaverse/auth-sdk)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
 ## 功能特性
 
-- 🔐 **邮箱登录/注册** - 传统用户名密码认证
-- 🌐 **OAuth 第三方登录** - 支持 Google、Discord、GitHub
-- 🎨 **精美登录 UI** - 开箱即用的登录弹窗组件
-- 📱 **完全响应式** - 适配移动端/平板/桌面
-- 🎭 **主题支持** - 暗色/亮色主题切换
+- 🔐 **用户认证** - 注册、登录、登出、密码重置
+- 🌐 **OAuth登录** - Google、Discord、GitHub 第三方登录
+- 🎨 **登录UI组件** - 开箱即用的精美登录弹窗
+- 📦 **容器管理** - Container 注册、心跳、状态查询
+- 🛍️ **技能市场** - Marketplace Skills 浏览、安装、卸载
+- 🗣️ **语音服务** - Speech Token 获取
+- 🌍 **多环境支持** - Production、Staging、Development、Local
 - ⚡ **TypeScript** - 完整的类型定义
-- 🔒 **安全** - 内置 CSRF 保护
-- 🌍 **多环境支持** - 一键切换生产/测试/开发环境
+- 🔧 **认证集成** - 内置Auth、Hooks系统支持
 
 ## 安装
 
 ```bash
-npm install @seaverseai/auth-sdk
+npm install @seaverse/auth-sdk
+# 或
+pnpm add @seaverse/auth-sdk
 ```
 
-## 快速开始
+## 核心概念
+
+### App ID 和多租户架构
+
+**重要**: 从 v0.2.0 开始，`appId` 是初始化 SDK 时的**必需参数**。
+
+#### 什么是 App ID？
+
+每个应用都有唯一的 `app_id`：
+- `app_id = "your app id"`
+
+#### 多租户隔离
+
+- 用户数据按 `app_id` 隔离
+- 同一邮箱可在不同应用中注册，使用不同密码
+- 每个应用拥有独立的用户池
+
+#### X-App-ID 请求头
+
+SDK 会自动在**每个请求**的请求头中添加 `X-App-ID`，无需手动设置：
+
+```typescript
+const client = new SeaVerseBackendAPIClient({
+  appId: 'game-abc123',  // SDK 自动将此值添加到所有请求的 X-App-ID header
+});
+
+// 所有 API 调用都会自动携带 X-App-ID: game-abc123
+await client.login({ email, password });
+await client.getCurrentUser();
+```
 
-### 1. API 客户端使用
+## 快速开始
 
-#### 方式 A：指定环境（推荐）
+### 1. 基本使用
 
 ```typescript
-import { SeaVerseBackendAPIClient } from '@seaverseai/auth-sdk';
+import { SeaVerseBackendAPIClient } from '@seaverse/auth-sdk';
 
-// 正式环境
+// 方式1: SeaVerse 平台应用（自动检测环境）
 const client = new SeaVerseBackendAPIClient({
-  environment: 'production',  // 'production' | 'staging' | 'development' | 'local'
+  appId: 'your app id', // 必需：应用ID
 });
 
-// 或者测试环境
+// 方式2: 第三方应用（指定环境）
 const client = new SeaVerseBackendAPIClient({
-  environment: 'staging',
+  appId: 'your app id',        // 必需：您的应用ID
+  environment: 'production',   // 'production' | 'staging' | 'development' | 'local'
 });
-```
 
-#### 方式 B：自动检测环境
+// 方式3: 自定义URL
+const client = new SeaVerseBackendAPIClient({
+  appId: 'your app id',             // 必需：您的应用ID
+  baseURL: 'https://custom-api.example.com',
+});
 
-```typescript
-import { SeaVerseBackendAPIClient } from '@seaverseai/auth-sdk';
+// 健康检查
+const health = await client.getHealth();
+console.log('Health:', health);
+```
 
-// SDK 会根据当前域名自动选择环境
-const client = new SeaVerseBackendAPIClient();
+### 2. 用户认证
 
-// 注册
+```typescript
+// 注册新用户
 const registerResult = await client.register({
   email: 'user@example.com',
-  password: 'password123',
+  password: 'SecurePassword123',
+  username: 'johndoe',              // 可选，未提供则从邮箱自动生成
+  invitation_code: 'INVITE123',     // 可选
 });
 
 // 登录
 const loginResult = await client.login({
   email: 'user@example.com',
-  password: 'password123',
+  password: 'SecurePassword123',
 });
 
-// 保存 token
+// 保存token
 localStorage.setItem('token', loginResult.token);
 
-// 获取当前用户
+// 获取当前用户信息
 const user = await client.getCurrentUser();
+console.log('User:', user);
+console.log('App ID:', user.app_id);           // 多租户应用ID
+console.log('Email verified:', user.email_verified);
 
 // 登出
 await client.logout();
+
+// 忘记密码
+await client.forgotPassword({
+  email: 'user@example.com',
+});
+
+// 重置密码
+await client.resetPassword({
+  token: 'reset-token-from-email',
+  new_password: 'NewSecurePassword123',
+});
+```
+
+### 3. OAuth 第三方登录
+
+#### Google 登录
+
+```typescript
+// 步骤1: 获取Google授权码后，交换token
+const result = await client.googleCodeToToken({
+  code: 'google-auth-code',
+  redirectUri: 'https://yourdomain.com/auth/callback',
+});
+
+localStorage.setItem('token', result.token);
+
+// 解绑Google账号
+await client.unlinkGoogle();
+```
+
+#### Discord 登录
+
+```typescript
+const result = await client.discordCodeToToken({
+  code: 'discord-auth-code',
+  redirectUri: 'https://yourdomain.com/auth/callback',
+});
+
+// 解绑Discord账号
+await client.unlinkDiscord();
 ```
 
-### 2. 使用登录弹窗 UI
+#### GitHub 登录
 
 ```typescript
-import { SeaVerseBackendAPIClient, createAuthModal } from '@seaverseai/auth-sdk';
-import '@seaverseai/auth-sdk/src/auth-modal.css';
+const result = await client.githubCodeToToken({
+  code: 'github-auth-code',
+  redirectUri: 'https://yourdomain.com/auth/callback',
+});
+
+// 解绑GitHub账号
+await client.unlinkGithub();
+```
+
+### 4. 使用登录UI组件
+
+SDK 提供精美的登录弹窗组件，支持深色和浅色两种主题：
+
+#### 主题对比
+
+| 主题 | 设计风格 | 适用场景 |
+|------|---------|---------|
+| **Dark** 🌙 | 动态网格渐变 + 玻璃态效果 | 科技感产品、游戏平台、深色界面应用 |
+| **Light** ☀️ | 提升的卡片设计 + 柔和阴影 | 商务应用、内容平台、浅色界面应用 |
+
+#### 基础用法
+
+```typescript
+import { SeaVerseBackendAPIClient, AuthModal } from '@seaverse/auth-sdk';
+import '@seaverse/auth-sdk/auth-modal.css'; // 导入样式
 
 const client = new SeaVerseBackendAPIClient({
-  baseURL: 'https://account-hub.sg.seaverse.dev',
+  appId: 'your app id',         // 必需：您的应用ID
+  environment: 'production',
 });
 
-const authModal = createAuthModal({
+// 创建登录弹窗（深色主题）
+const authModal = new AuthModal({
   client,
-  theme: 'dark', // 'dark' 或 'light'
+  theme: 'dark', // 'dark' | 'light' - 默认为 'dark'
 
+  // 登录成功回调
   onLoginSuccess: (token, user) => {
     localStorage.setItem('token', token);
     console.log('登录成功:', user);
   },
 
+  // 注册成功回调
   onSignupSuccess: (token, user) => {
     localStorage.setItem('token', token);
     console.log('注册成功:', user);
   },
 
+  // 错误回调
   onError: (error) => {
-    console.error('错误:', error.message);
+    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
+    },
   },
 });
 
@@ -106,127 +233,276 @@ authModal.show('login');
 
 // 显示注册界面
 authModal.show('signup');
-```
 
-## OAuth 第三方登录
+// 隐藏弹窗
+authModal.hide();
+
+// 销毁弹窗
+authModal.destroy();
+#### OAuth 配置说明
+
+`oauthConfig` 参数是**完全可选的**：
 
-### 1. 配置 OAuth
+- 如果**不提供** `oauthConfig`，则不会显示任何第三方登录按钮
+- 如果**部分配置**（如只配置 Google），则只显示已配置的按钮
+- 如果**完整配置**所有平台，则显示所有第三方登录按钮
+
+**配置字段说明**：
+- `clientId`：**必填** - OAuth 应用的客户端 ID
+- `redirectUri`：**可选** - OAuth 回调地址，不填则默认为 `window.location.origin`
+- `scope`：**可选** - OAuth 权限范围，每个平台有默认值
 
 ```typescript
-const authModal = createAuthModal({
-  client,
+// 示例1：无OAuth按钮
+const client1 = new SeaVerseBackendAPIClient({ appId: 'your app id' });
+const authModal1 = new AuthModal({
+  client: client1,
+  theme: 'dark',
+  // 不传 oauthConfig，不显示任何OAuth按钮
+});
 
+// 示例2：只显示Google登录
+const client2 = new SeaVerseBackendAPIClient({ appId: 'your app id' });
+const authModal2 = new AuthModal({
+  client: client2,
+  theme: 'light',
   oauthConfig: {
     google: {
       clientId: 'YOUR_GOOGLE_CLIENT_ID',
-      redirectUri: 'https://yourdomain.com/auth/callback',
+      // redirectUri 可选，不填则默认为 window.location.origin
+    },
+    // Discord 和 GitHub 未配置，不会显示这些按钮
+  },
+});
+
+// 示例3：显示所有OAuth按钮（自定义 redirectUri）
+const client3 = new SeaVerseBackendAPIClient({ appId: 'your app id' });
+const authModal3 = new AuthModal({
+  client: client3,
+  theme: 'dark',
+  oauthConfig: {
+    google: {
+      clientId: '...',
+      redirectUri: 'https://yourdomain.com/auth/callback' // 自定义回调地址
     },
     discord: {
-      clientId: 'YOUR_DISCORD_CLIENT_ID',
-      redirectUri: 'https://yourdomain.com/auth/callback',
+      clientId: '...'
+      // redirectUri 可选，不填则默认为 window.location.origin
     },
     github: {
-      clientId: 'YOUR_GITHUB_CLIENT_ID',
-      redirectUri: 'https://yourdomain.com/auth/callback',
+      clientId: '...'
+      // redirectUri 可选，不填则默认为 window.location.origin
     },
   },
+});
+```
 
-  onLoginSuccess: (token, user) => {
-    localStorage.setItem('token', token);
+### 5. 容器管理
+
+```typescript
+// 列出所有容器
+const containers = await client.listContainers();
+
+// 注册新容器
+const result = await client.registerContainer({
+  containerId: 'container-123',
+  metadata: {
+    version: '1.0.0',
+    capabilities: ['skill-execution'],
   },
 });
 
-authModal.show('login');
-```
+// 获取容器信息
+const container = await client.getContainer({
+  containerId: 'container-123',
+});
 
-### 2. 处理 OAuth 回调
+// 容器心跳
+await client.containerHeartbeat({
+  containerId: 'container-123',
+  status: 'healthy',
+});
 
-在你的回调页面（如 `/auth/callback`）添加：
+// 注销容器
+await client.unregisterContainer({
+  containerId: 'container-123',
+});
+
+// 获取容器统计
+const stats = await client.getContainerStats();
+```
+
+### 6. 技能市场
 
 ```typescript
-import { SeaVerseBackendAPIClient, AuthModal } from '@seaverseai/auth-sdk';
+// 列出市场技能
+const skills = await client.listMarketplaceSkills({
+  category: 'productivity',
+  page: 1,
+  pageSize: 20,
+});
 
-const client = new SeaVerseBackendAPIClient({
-  baseURL: 'https://account-hub.sg.seaverse.dev',
+// 获取技能详情
+const skill = await client.getMarketplaceSkill({
+  skillId: 'skill-123',
 });
 
-// 自动处理 OAuth 回调
-AuthModal.handleOAuthCallbackFromUrl(client, {
-  onLoginSuccess: (token, user) => {
-    localStorage.setItem('token', token);
-    window.location.href = '/dashboard';
-  },
-  onError: (error) => {
-    console.error('登录失败:', error);
-    window.location.href = '/';
-  },
+// 安装技能
+await client.installSkill({
+  skillId: 'skill-123',
 });
-```
 
-### 3. 获取 OAuth Client ID
+// 列出已安装的技能
+const userSkills = await client.listUserSkills();
 
-| 平台 | 配置地址 |
-|------|---------|
-| Google | https://console.cloud.google.com/ → 创建 OAuth 客户端 ID |
-| Discord | https://discord.com/developers/applications → OAuth2 设置 |
-| GitHub | https://github.com/settings/developers → OAuth Apps |
+// 卸载技能
+await client.uninstallSkill({
+  skillId: 'skill-123',
+});
+```
 
-**重要**：在 OAuth 应用中配置的 Redirect URI 必须与代码中的 `redirectUri` 完全一致。
+### 7. 其他功能
 
-## API 参考
+```typescript
+// 获取API Service Token
+const apiToken = await client.getApiServiceToken();
 
-### 认证方法
+// 获取对话状态
+const status = await client.getConversationStatus({
+  conversationId: 'conv-123',
+});
 
-```typescript
-// 注册
-await client.register({ email, password, invitationCode? })
+// 获取语音Token
+const speechToken = await client.getSpeechToken();
+```
 
-// 登录
-await client.login({ email, password })
+## 高级配置
 
-// 获取当前用户
-await client.getCurrentUser()
+### 自定义认证
 
-// 登出
-await client.logout()
+```typescript
+import { AuthFactory } from '@seaverse/auth-sdk';
 
-// 忘记密码
-await client.forgotPassword({ email })
+const client = new SeaVerseBackendAPIClient({
+  appId: 'your app id',         // 必需：应用ID
+  environment: 'production',
 
-// 重置密码
-await client.resetPassword({ token, newPassword })
+  // 使用JWT认证
+  auth: AuthFactory.create({
+    type: 'jwt',
+    credentials: {
+      type: 'jwt',
+      token: localStorage.getItem('token'),
+    },
+  }),
+});
 ```
 
-### OAuth 方法
+### 自定义Hooks
 
 ```typescript
-// Google 登录
-await client.googleCodeToToken({ code })
+import { BuiltInHooks } from '@seaverse/auth-sdk';
 
-// Discord 登录
-await client.discordCodeToToken({ code })
+const client = new SeaVerseBackendAPIClient({
+  appId: 'your app id',         // 必需：应用ID
+  environment: 'production',
+
+  hooks: {
+    hooks: [
+      // 日志Hook
+      BuiltInHooks.createLoggerHook({
+        logLevel: 'debug',
+        logRequestBody: true,
+        logResponseBody: true,
+      }),
+
+      // 请求ID Hook
+      BuiltInHooks.createRequestIdHook(),
+
+      // 自定义Hook
+      {
+        type: 'beforeRequest',
+        name: 'custom-hook',
+        priority: 100,
+        handler: async (context) => {
+          console.log('Before request:', context.config.url);
+        },
+      },
+    ],
+  },
+});
+```
 
-// GitHub 登录
-await client.githubCodeToToken({ code })
+### 环境配置
 
-// 解绑账号
-await client.unlinkGoogle()
-await client.unlinkDiscord()
-await client.unlinkGithub()
-```
+SDK支持以下环境：
 
-### UI 方法
+| 环境 | 描述 | BaseURL |
+|------|------|---------|
+| `production` | 生产环境 | `https://api.seaverse.com` |
+| `staging` | 测试环境 | `https://api.staging.seaverse.dev` |
+| `development` | 开发环境 | `https://api.dev.seaverse.dev` |
+| `local` | 本地环境 | `http://localhost:3000` |
 
-```typescript
-// 显示登录/注册
-authModal.show('login')  // 或 'signup'
+自动检测规则：
+- `*.seaverse.com` → production
+- `*.staging.seaverse.dev` → staging
+- `*.dev.seaverse.dev` → development
+- `localhost` → local
 
-// 隐藏弹窗
-authModal.hide()
+## API 参考
 
-// 销毁弹窗
-authModal.destroy()
-```
+### 认证相关
+
+| 方法 | 参数 | 返回值 | 说明 |
+|------|------|--------|------|
+| `register()` | `{ email, password, username?, invitation_code? }` | `RegisterResponse` | 注册新用户 |
+| `login()` | `{ email, password }` | `LoginResponse` | 用户登录 |
+| `getCurrentUser()` | - | `User` | 获取当前用户 |
+| `logout()` | - | `SuccessResponse` | 登出 |
+| `forgotPassword()` | `{ email }` | `SuccessResponse` | 忘记密码 |
+| `resetPassword()` | `{ token, new_password }` | `SuccessResponse` | 重置密码 |
+| `getApiServiceToken()` | - | `ApiServiceTokenResponse` | 获取API Token |
+
+### OAuth相关
+
+| 方法 | 参数 | 返回值 | 说明 |
+|------|------|--------|------|
+| `googleCodeToToken()` | `{ code, redirectUri }` | `OAuthTokenResponse` | Google登录 |
+| `discordCodeToToken()` | `{ code, redirectUri }` | `OAuthTokenResponse` | Discord登录 |
+| `githubCodeToToken()` | `{ code, redirectUri }` | `OAuthTokenResponse` | GitHub登录 |
+| `unlinkGoogle()` | - | `SuccessResponse` | 解绑Google |
+| `unlinkDiscord()` | - | `SuccessResponse` | 解绑Discord |
+| `unlinkGithub()` | - | `SuccessResponse` | 解绑GitHub |
+
+### 容器管理
+
+| 方法 | 参数 | 返回值 | 说明 |
+|------|------|--------|------|
+| `listContainers()` | - | `ContainerListResponse` | 列出容器 |
+| `registerContainer()` | `{ containerId, metadata }` | `SuccessResponse` | 注册容器 |
+| `getContainer()` | `{ containerId }` | `Container` | 获取容器信息 |
+| `unregisterContainer()` | `{ containerId }` | `SuccessResponse` | 注销容器 |
+| `containerHeartbeat()` | `{ containerId, status }` | `SuccessResponse` | 容器心跳 |
+| `getContainerStats()` | - | `ContainerStatsResponse` | 容器统计 |
+
+### 技能市场
+
+| 方法 | 参数 | 返回值 | 说明 |
+|------|------|--------|------|
+| `listMarketplaceSkills()` | `{ category?, page?, pageSize? }` | `MarketplaceSkillsListResponse` | 列出市场技能 |
+| `getMarketplaceSkill()` | `{ skillId }` | `MarketplaceSkill` | 获取技能详情 |
+| `installSkill()` | `{ skillId }` | `SuccessResponse` | 安装技能 |
+| `listUserSkills()` | - | `UserInstalledSkillsListResponse` | 列出已安装技能 |
+| `uninstallSkill()` | `{ skillId }` | `SuccessResponse` | 卸载技能 |
+
+### 其他
+
+| 方法 | 参数 | 返回值 | 说明 |
+|------|------|--------|------|
+| `getHealth()` | - | `HealthResponse` | 健康检查 |
+| `getConversationStatus()` | `{ conversationId }` | `ConversationStatusResponse` | 获取对话状态 |
+| `getSpeechToken()` | - | `SpeechTokenResponse` | 获取语音Token |
 
 ## 类型定义
 
@@ -234,12 +510,21 @@ authModal.destroy()
 // 用户信息
 interface User {
   id?: string;
+  app_id?: string | null;           // 应用ID（多租户支持）
   email?: string;
   username?: string;
-  emailVerified?: boolean;
-  googleId?: string;
-  discordId?: string;
-  githubId?: string;
+  created_at?: number;               // Unix时间戳
+  email_verified?: boolean;          // 邮箱验证状态
+  google_id?: string | null;         // Google账号ID
+  discord_id?: string | null;        // Discord账号ID
+  github_id?: string | null;         // GitHub账号ID
+
+  // 已弃用字段（向后兼容）
+  createdAt?: number;                // @deprecated 使用 created_at
+  emailVerified?: boolean;           // @deprecated 使用 email_verified
+  googleId?: string;                 // @deprecated 使用 google_id
+  discordId?: string;                // @deprecated 使用 discord_id
+  githubId?: string;                 // @deprecated 使用 github_id
 }
 
 // 登录响应
@@ -255,119 +540,141 @@ interface RegisterResponse {
   userId: string;
 }
 
-// OAuth 配置
+// AuthModal选项
+interface AuthModalOptions {
+  client: SeaVerseBackendAPIClient;
+  theme?: 'dark' | 'light';
+  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;
-    scope?: string;  // 默认: 'openid email profile'
+    clientId: string;        // 必填
+    redirectUri?: string;    // 可选，默认为 window.location.origin
+    scope?: string;          // 可选，默认为 'openid email profile'
   };
   discord?: {
-    clientId: string;
-    redirectUri: string;
-    scope?: string;  // 默认: 'identify email'
+    clientId: string;        // 必填
+    redirectUri?: string;    // 可选，默认为 window.location.origin
+    scope?: string;          // 可选，默认为 'identify email'
   };
   github?: {
-    clientId: string;
-    redirectUri: string;
-    scope?: string;  // 默认: 'read:user user:email'
+    clientId: string;        // 必填
+    redirectUri?: string;    // 可选，默认为 window.location.origin
+    scope?: string;          // 可选，默认为 'read:user user:email'
   };
 }
 ```
 
 ## 完整示例
 
-```html
-<!DOCTYPE html>
-<html>
-<head>
-  <meta charset="UTF-8">
-  <title>登录示例</title>
-  <link rel="stylesheet" href="node_modules/@seaverseai/auth-sdk/src/auth-modal.css">
-</head>
-<body>
-  <h1>欢迎</h1>
-  <button id="loginBtn">登录</button>
-
-  <script type="module">
-    import { SeaVerseBackendAPIClient, createAuthModal } from '@seaverseai/auth-sdk';
-
-    const client = new SeaVerseBackendAPIClient({
-      baseURL: 'https://account-hub.sg.seaverse.dev',
-    });
-
-    const authModal = createAuthModal({
-      client,
-      theme: 'dark',
-
-      oauthConfig: {
-        google: {
-          clientId: 'YOUR_GOOGLE_CLIENT_ID',
-          redirectUri: window.location.origin + '/callback.html',
-        },
-      },
+查看 [examples/auth-sdk-demo](../../examples/auth-sdk-demo) 目录获取完整的可运行示例。
 
-      onLoginSuccess: (token, user) => {
-        localStorage.setItem('token', token);
-        alert('登录成功: ' + user.email);
-      },
-    });
-
-    document.getElementById('loginBtn').onclick = () => {
-      authModal.show('login');
-    };
-  </script>
-</body>
-</html>
+```bash
+# 运行示例
+cd examples/auth-sdk-demo
+pnpm install
+pnpm dev
 ```
 
-## React 集成
+## 从旧版本迁移
 
-```tsx
-import { useEffect, useState } from 'react';
-import { SeaVerseBackendAPIClient, createAuthModal } from '@seaverseai/auth-sdk';
-import '@seaverseai/auth-sdk/src/auth-modal.css';
+### v0.1.x → v0.2.0 升级指南
 
-function App() {
-  const [authModal, setAuthModal] = useState(null);
+#### 1. 向后兼容性
+好消息！v0.2.0 完全向后兼容，现有代码**无需修改**即可继续工作。
 
-  useEffect(() => {
-    const client = new SeaVerseBackendAPIClient({
-      baseURL: 'https://account-hub.sg.seaverse.dev',
-    });
+#### 2. 推荐的迁移步骤
 
-    const modal = createAuthModal({
-      client,
-      onLoginSuccess: (token) => {
-        localStorage.setItem('token', token);
-      },
-    });
+虽然不是必须的，但我们建议逐步迁移到新的字段命名规范：
 
-    setAuthModal(modal);
-    return () => modal?.destroy();
-  }, []);
+```typescript
+// 旧代码（仍然可用）
+const user = await client.getCurrentUser();
+console.log(user.emailVerified);  // ⚠️ 已弃用但可用
+console.log(user.createdAt);      // ⚠️ 已弃用但可用
 
-  return (
-    <button onClick={() => authModal?.show('login')}>
-      登录
-    </button>
-  );
-}
+// 新代码（推荐）
+const user = await client.getCurrentUser();
+console.log(user.email_verified); // ✅ 推荐使用
+console.log(user.created_at);     // ✅ 推荐使用
+console.log(user.app_id);         // ✅ 新字段：多租户支持
 ```
 
-## 常见问题
+#### 3. 注册接口更新
+
+```typescript
+// 旧代码（仍然可用）
+await client.register({
+  email: 'user@example.com',
+  password: 'password123',
+  invitationCode: 'INVITE123',  // ⚠️ 已弃用但可用
+});
+
+// 新代码（推荐）
+await client.register({
+  email: 'user@example.com',
+  password: 'password123',
+  username: 'myusername',       // ✨ 新功能
+  invitation_code: 'INVITE123', // ✅ 推荐使用
+});
+```
+
+#### 4. 密码重置接口更新
+
+```typescript
+// 旧代码（需要更新）
+await client.resetPassword({
+  token: 'reset-token',
+  newPassword: 'NewPass123',    // ⚠️ 已弃用
+});
 
-### OAuth redirect_uri_mismatch 错误？
+// 新代码（推荐）
+await client.resetPassword({
+  token: 'reset-token',
+  new_password: 'NewPass123',   // ✅ 推荐使用
+});
+```
 
-确保 OAuth 应用配置中的重定向 URI 与代码中完全一致（包括协议、域名、端口、路径）。
+#### 5. TypeScript 类型提示
 
-### 如何自动携带 Token？
+如果你使用 TypeScript，编译器会自动提示已弃用的字段：
 
 ```typescript
-import { AuthFactory } from '@seaverseai/auth-sdk';
+const user = await client.getCurrentUser();
+user.emailVerified;  // TypeScript 会显示删除线和弃用警告
+user.email_verified; // ✅ 无警告
+```
 
-const client = new SeaVerseBackendAPIClient({
-  baseURL: 'https://account-hub.sg.seaverse.dev',
+#### 6. 多租户功能（新增）
+
+如果你的应用需要支持多租户架构，可以使用新的 `app_id` 字段：
+
+```typescript
+const user = await client.getCurrentUser();
+
+console.log('your app id:', user.app_id);
+```
+
+## 常见问题
+
+### 如何处理认证token？
+
+```typescript
+// 登录成功后保存token
+const loginResult = await client.login({ email, password });
+localStorage.setItem('token', loginResult.token);
+
+// 创建带认证的client
+import { AuthFactory } from '@seaverse/auth-sdk';
+
+const authenticatedClient = new SeaVerseBackendAPIClient({
+  appId: 'your app id',         // 必需：应用ID
+  environment: 'production',
   auth: AuthFactory.create({
     type: 'jwt',
     credentials: {
@@ -378,20 +685,28 @@ const client = new SeaVerseBackendAPIClient({
 });
 ```
 
-### 如何只启用部分 OAuth 登录？
+### OAuth redirect_uri_mismatch错误？
 
-只配置需要的平台即可，未配置的平台按钮点击时会提示错误：
+确保OAuth应用配置中的重定向URI与代码中的`redirectUri`完全一致（包括协议、域名、端口、路径）。
+
+### 如何自定义请求超时？
 
 ```typescript
-oauthConfig: {
-  google: { /* ... */ },
-  // 不配置 discord 和 github
-}
+const client = new SeaVerseBackendAPIClient({
+  appId: 'your app id',         // 必需：应用ID
+  environment: 'production',
+  timeout: 30000,            // 30秒
+});
 ```
 
-### 本地开发如何测试 OAuth？
+### 本地开发如何连接到本地API？
 
-大多数 OAuth 提供商允许 `http://localhost:PORT` 作为开发环境的重定向 URI。
+```typescript
+const client = new SeaVerseBackendAPIClient({
+  appId: 'your app id',         // 必需：应用ID
+  environment: 'local',      // 或使用 baseURL: 'http://localhost:3000'
+});
+```
 
 ## 开发
 
@@ -400,18 +715,55 @@ oauthConfig: {
 pnpm install
 
 # 构建
-pnpm run build
+pnpm build
+
+# Watch模式
+pnpm dev
 
 # 测试
 pnpm test
 ```
 
-## License
+## 相关链接
 
-MIT © SeaVerse Team
+- 📦 [NPM Package](https://www.npmjs.com/package/@seaverse/auth-sdk)
+- 📖 [示例项目](../../examples/auth-sdk-demo)
+- 🐛 [Issues](https://github.com/seaverseai/sv-sdk/issues)
+- 💬 [Discussions](https://github.com/seaverseai/sv-sdk/discussions)
 
-## 技术支持
+## License
 
-- 📧 Email: support@seaverse.com
-- 🐛 Issues: https://github.com/seaverseai/sv-sdk/issues
-- 📖 Docs: https://docs.seaverse.dev
+MIT © [SeaVerse Team](mailto:support@seaverse.com)
+
+## 更新日志
+
+### v0.2.0 (当前版本)
+- 🔄 **API路径更新**: 所有认证API从 `/api/auth/*` 迁移到 `/sdk/v1/auth/*`
+- 🏢 **多租户支持**: User模型新增 `app_id` 字段，支持多应用隔离
+- 🔑 **重要变更**: `appId` 现在是**必需参数**，SDK 自动在所有请求中添加 `X-App-ID` 请求头
+- ✨ **新功能**:
+  - 注册时支持自定义 `username`（可选）
+  - 所有字段标准化为 snake_case（保留 camelCase 向后兼容）
+- 📝 **字段更新**:
+  - `SeaVerseBackendAPIClientOptions`: 新增必需字段 `appId`
+  - `User`: 新增 `app_id`, `created_at`, `email_verified`, `google_id`, `discord_id`, `github_id`
+  - `RegisterRequest`: 新增 `username`, `invitation_code`
+  - `ResetPasswordRequest`: `newPassword` → `new_password`
+- ⚠️ **Breaking Changes**:
+  - 必须提供 `appId` 参数才能初始化 client
+  - API 路径变更需要后端支持
+- ✅ **向后兼容**: 除 `appId` 外，所有旧字段仍然可用
+
+### v0.1.5
+- 修复OAuth state管理，从sessionStorage切换到localStorage
+- 增强API响应处理
+
+### v0.1.4
+- 增强API响应处理
+- 优化错误处理
+
+### v0.1.2
+- 更新包名为@seaverse/auth-sdk
+- 添加多环境支持
+
+查看完整更新日志：[CHANGELOG.md](./CHANGELOG.md)