seaverse-auth-sdk 0.1.0

package/README.md

@@ -0,0 +1,399 @@
+# @seaverseai/auth-sdk
+
+SeaVerse 认证 SDK - 提供完整的用户认证功能和精美的登录注册 UI 组件
+
+[![npm version](https://img.shields.io/npm/v/@seaverseai/auth-sdk.svg)](https://www.npmjs.com/package/@seaverseai/auth-sdk)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## 功能特性
+
+- 🔐 **邮箱登录/注册** - 传统用户名密码认证
+- 🌐 **OAuth 第三方登录** - 支持 Google、Discord、GitHub
+- 🎨 **精美登录 UI** - 开箱即用的登录弹窗组件
+- 📱 **完全响应式** - 适配移动端/平板/桌面
+- 🎭 **主题支持** - 暗色/亮色主题切换
+- ⚡ **TypeScript** - 完整的类型定义
+- 🔒 **安全** - 内置 CSRF 保护
+
+## 安装
+
+```bash
+npm install @seaverseai/auth-sdk
+```
+
+## 快速开始
+
+### 1. API 客户端使用
+
+```typescript
+import { SeaVerseBackendAPIClient } from '@seaverseai/auth-sdk';
+
+const client = new SeaVerseBackendAPIClient({
+  baseURL: 'https://web.seaverse.dev',
+});
+
+// 注册
+const registerResult = await client.register({
+  email: 'user@example.com',
+  password: 'password123',
+});
+
+// 登录
+const loginResult = await client.login({
+  email: 'user@example.com',
+  password: 'password123',
+});
+
+// 保存 token
+localStorage.setItem('token', loginResult.token);
+
+// 获取当前用户
+const user = await client.getCurrentUser();
+
+// 登出
+await client.logout();
+```
+
+### 2. 使用登录弹窗 UI
+
+```typescript
+import { SeaVerseBackendAPIClient, createAuthModal } from '@seaverseai/auth-sdk';
+import '@seaverseai/auth-sdk/src/auth-modal.css';
+
+const client = new SeaVerseBackendAPIClient({
+  baseURL: 'https://web.seaverse.dev',
+});
+
+const authModal = createAuthModal({
+  client,
+  theme: 'dark', // 'dark' 或 'light'
+
+  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);
+  },
+});
+
+// 显示登录界面
+authModal.show('login');
+
+// 显示注册界面
+authModal.show('signup');
+```
+
+## OAuth 第三方登录
+
+### 1. 配置 OAuth
+
+```typescript
+const authModal = createAuthModal({
+  client,
+
+  oauthConfig: {
+    google: {
+      clientId: 'YOUR_GOOGLE_CLIENT_ID',
+      redirectUri: 'https://yourdomain.com/auth/callback',
+    },
+    discord: {
+      clientId: 'YOUR_DISCORD_CLIENT_ID',
+      redirectUri: 'https://yourdomain.com/auth/callback',
+    },
+    github: {
+      clientId: 'YOUR_GITHUB_CLIENT_ID',
+      redirectUri: 'https://yourdomain.com/auth/callback',
+    },
+  },
+
+  onLoginSuccess: (token, user) => {
+    localStorage.setItem('token', token);
+  },
+});
+
+authModal.show('login');
+```
+
+### 2. 处理 OAuth 回调
+
+在你的回调页面（如 `/auth/callback`）添加：
+
+```typescript
+import { SeaVerseBackendAPIClient, AuthModal } from '@seaverseai/auth-sdk';
+
+const client = new SeaVerseBackendAPIClient({
+  baseURL: 'https://web.seaverse.dev',
+});
+
+// 自动处理 OAuth 回调
+AuthModal.handleOAuthCallbackFromUrl(client, {
+  onLoginSuccess: (token, user) => {
+    localStorage.setItem('token', token);
+    window.location.href = '/dashboard';
+  },
+  onError: (error) => {
+    console.error('登录失败:', error);
+    window.location.href = '/';
+  },
+});
+```
+
+### 3. 获取 OAuth Client ID
+
+| 平台 | 配置地址 |
+|------|---------|
+| Google | https://console.cloud.google.com/ → 创建 OAuth 客户端 ID |
+| Discord | https://discord.com/developers/applications → OAuth2 设置 |
+| GitHub | https://github.com/settings/developers → OAuth Apps |
+
+**重要**：在 OAuth 应用中配置的 Redirect URI 必须与代码中的 `redirectUri` 完全一致。
+
+## API 参考
+
+### 认证方法
+
+```typescript
+// 注册
+await client.register({ email, password, invitationCode? })
+
+// 登录
+await client.login({ email, password })
+
+// 获取当前用户
+await client.getCurrentUser()
+
+// 登出
+await client.logout()
+
+// 忘记密码
+await client.forgotPassword({ email })
+
+// 重置密码
+await client.resetPassword({ token, newPassword })
+```
+
+### OAuth 方法
+
+```typescript
+// Google 登录
+await client.googleCodeToToken({ code })
+
+// Discord 登录
+await client.discordCodeToToken({ code })
+
+// GitHub 登录
+await client.githubCodeToToken({ code })
+
+// 解绑账号
+await client.unlinkGoogle()
+await client.unlinkDiscord()
+await client.unlinkGithub()
+```
+
+### UI 方法
+
+```typescript
+// 显示登录/注册
+authModal.show('login')  // 或 'signup'
+
+// 隐藏弹窗
+authModal.hide()
+
+// 销毁弹窗
+authModal.destroy()
+```
+
+## 类型定义
+
+```typescript
+// 用户信息
+interface User {
+  id?: string;
+  email?: string;
+  username?: string;
+  emailVerified?: boolean;
+  googleId?: string;
+  discordId?: string;
+  githubId?: string;
+}
+
+// 登录响应
+interface LoginResponse {
+  token: string;
+  user: User;
+}
+
+// 注册响应
+interface RegisterResponse {
+  success: boolean;
+  message: string;
+  userId: string;
+}
+
+// OAuth 配置
+interface OAuthConfig {
+  google?: {
+    clientId: string;
+    redirectUri: string;
+    scope?: string;  // 默认: 'openid email profile'
+  };
+  discord?: {
+    clientId: string;
+    redirectUri: string;
+    scope?: string;  // 默认: 'identify email'
+  };
+  github?: {
+    clientId: string;
+    redirectUri: string;
+    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://web.seaverse.dev',
+    });
+
+    const authModal = createAuthModal({
+      client,
+      theme: 'dark',
+
+      oauthConfig: {
+        google: {
+          clientId: 'YOUR_GOOGLE_CLIENT_ID',
+          redirectUri: window.location.origin + '/callback.html',
+        },
+      },
+
+      onLoginSuccess: (token, user) => {
+        localStorage.setItem('token', token);
+        alert('登录成功: ' + user.email);
+      },
+    });
+
+    document.getElementById('loginBtn').onclick = () => {
+      authModal.show('login');
+    };
+  </script>
+</body>
+</html>
+```
+
+## React 集成
+
+```tsx
+import { useEffect, useState } from 'react';
+import { SeaVerseBackendAPIClient, createAuthModal } from '@seaverseai/auth-sdk';
+import '@seaverseai/auth-sdk/src/auth-modal.css';
+
+function App() {
+  const [authModal, setAuthModal] = useState(null);
+
+  useEffect(() => {
+    const client = new SeaVerseBackendAPIClient({
+      baseURL: 'https://web.seaverse.dev',
+    });
+
+    const modal = createAuthModal({
+      client,
+      onLoginSuccess: (token) => {
+        localStorage.setItem('token', token);
+      },
+    });
+
+    setAuthModal(modal);
+    return () => modal?.destroy();
+  }, []);
+
+  return (
+    <button onClick={() => authModal?.show('login')}>
+      登录
+    </button>
+  );
+}
+```
+
+## 常见问题
+
+### OAuth redirect_uri_mismatch 错误？
+
+确保 OAuth 应用配置中的重定向 URI 与代码中完全一致（包括协议、域名、端口、路径）。
+
+### 如何自动携带 Token？
+
+```typescript
+import { AuthFactory } from '@seaverseai/auth-sdk';
+
+const client = new SeaVerseBackendAPIClient({
+  baseURL: 'https://web.seaverse.dev',
+  auth: AuthFactory.create({
+    type: 'jwt',
+    credentials: {
+      type: 'jwt',
+      token: localStorage.getItem('token'),
+    },
+  }),
+});
+```
+
+### 如何只启用部分 OAuth 登录？
+
+只配置需要的平台即可，未配置的平台按钮点击时会提示错误：
+
+```typescript
+oauthConfig: {
+  google: { /* ... */ },
+  // 不配置 discord 和 github
+}
+```
+
+### 本地开发如何测试 OAuth？
+
+大多数 OAuth 提供商允许 `http://localhost:PORT` 作为开发环境的重定向 URI。
+
+## 开发
+
+```bash
+# 安装依赖
+pnpm install
+
+# 构建
+pnpm run build
+
+# 测试
+pnpm test
+```
+
+## License
+
+MIT © SeaVerse Team
+
+## 技术支持
+
+- 📧 Email: support@seaverse.com
+- 🐛 Issues: https://github.com/seaverseai/sv-sdk/issues
+- 📖 Docs: https://docs.seaverse.dev