@choiceform/shared-auth 0.1.17 → 0.1.18

package/README.md

@@ -1,208 +1,360 @@
 # @choiceform/shared-auth
 
-共享认证包 - 基于 Better Auth 的统一认证解决方案
+基于 Better Auth + Legend State 的共享认证库。
 
-## 功能特性
+## 架构设计
 
-- Better Auth 集成（OAuth、Magic Link）
-- Legend State 状态管理
-- 自动伴生团队设置
-- Token 自动管理
-- 完整 TypeScript 类型支持
-- 预配置 API 客户端
-
-## 安装
-
-```bash
-pnpm add @choiceform/shared-auth
+```
+┌─────────────────────────────────────────────────────────────┐
+│                        createAuth()                          │
+│                         (core.ts)                            │
+├─────────────────────────────────────────────────────────────┤
+│                                                              │
+│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────────┐ │
+│  │  Store   │  │ Service  │  │   API    │  │    Hooks     │ │
+│  │  Layer   │  │  Layer   │  │  Layer   │  │    Layer     │ │
+│  │          │  │          │  │          │  │              │ │
+│  │authStore │  │authServ. │  │apiClient │  │useAuthSync   │ │
+│  │storeAct. │  │callback  │  │authApi   │  │useProtected  │ │
+│  │computed  │  │companion │  │orgApi    │  │useEmailVerif │ │
+│  └──────────┘  └──────────┘  └──────────┘  └──────────────┘ │
+│                                                              │
+└─────────────────────────────────────────────────────────────┘
 ```
 
-## 环境变量
+### 四层架构
 
-```bash
-VITE_ONEAUTH_BASE_URL=https://oneauth.choiceform.io
-```
+| 层级 | 职责 | 文件 |
+|------|------|------|
+| **Store Layer** | 响应式状态管理 | `store/state.ts`, `store/actions.ts`, `store/computed.ts` |
+| **Service Layer** | 业务逻辑 | `services/auth-service.ts`, `services/callback-service.ts`, `services/companion-team.ts` |
+| **API Layer** | HTTP 请求 | `api/client.ts`, `api/auth-api.ts`, `api/organization-api.ts`, `api/team-api.ts` |
+| **Hooks Layer** | React 专用 | `hooks/use-auth-sync.ts`, `hooks/use-protected-route.ts`, `hooks/use-email-verification.ts` |
 
 ## 快速开始
 
-### 初始化
-
 ```typescript
 import { initAuth } from "@choiceform/shared-auth"
 
-export const auth = initAuth({
-  baseURL: import.meta.env.VITE_ONEAUTH_BASE_URL,
-  tokenStorageKey: "auth-token",
+// 初始化
+const auth = initAuth({
+  baseURL: "https://api.example.com",
 })
+
+// 导出供全局使用
+export { auth }
 ```
 
-### 在应用中使用
+## Hooks（推荐使用）
+
+### useAuthSync
+
+认证状态同步，替代手动同步 Better Auth session：
 
 ```typescript
-import { use$ } from "@legendapp/state/react"
-import { auth } from "./lib/auth"
+import { useAuthSync } from "@choiceform/shared-auth"
 
 function App() {
-  const { isAuthenticated, user } = use$(auth.authStore)
+  useAuthSync(auth, {
+    skipCompanionTeamPaths: ['/auth/callback', '/auth/delete-success'],
+    onAuthChange: (isAuthenticated) => {
+      if (isAuthenticated) {
+        syncTheme()
+        syncLanguage()
+      }
+    }
+  })
+
+  return <YourApp />
+}
+```
+
+### useProtectedRoute
+
+路由保护，检查认证状态和邮箱验证：
 
-  if (!isAuthenticated) {
-    return <SignInPage />
+```typescript
+import { useProtectedRoute } from "@choiceform/shared-auth"
+
+function ProtectedRoute({ children }) {
+  const navigate = useNavigate()
+  const location = useLocation()
+
+  const { status, shouldRender, redirectPath } = useProtectedRoute(auth, {
+    pathname: location.pathname,
+    publicRoutePrefixes: ['/resources', '/public'],
+    requireEmailVerified: true,
+    lang: 'us'
+  })
+
+  useEffect(() => {
+    if (redirectPath) {
+      navigate(redirectPath, { replace: true })
+    }
+  }, [redirectPath])
+
+  if (!shouldRender) {
+    return <Loading />
   }
 
-  return <MainApp user={user} />
+  return <>{children}</>
 }
 ```
 
-### 登录
+### useEmailVerification
 
-```typescript
-// OAuth 登录
-const handleOAuthSignIn = async () => {
-  const callbackURL = new URL("/dashboard", window.location.origin)
-  const newUserCallbackURL = new URL("/dashboard?isNew=true", window.location.origin)
-  
-  await auth.authActions.signIn(
-    "github",
-    callbackURL.toString(),
-    newUserCallbackURL.toString()
-  )
-}
+邮箱验证流程：
 
-// Magic Link 登录
-const handleMagicLink = async (email: string) => {
-  const callbackURL = new URL("/dashboard", window.location.origin)
-  
-  await auth.authActions.signInWithMagicLink(
+```typescript
+import { useEmailVerification } from "@choiceform/shared-auth"
+
+function VerifyEmailPage({ email, lang }) {
+  const navigate = useNavigate()
+
+  const {
+    isLoading,
+    isAlreadyVerified,
+    isCountingDown,
+    countdown,
+    resendVerification,
+    changeEmail
+  } = useEmailVerification(auth, {
     email,
-    callbackURL.toString()
+    lang,
+    onRedirect: (path) => navigate(path),
+    onSendSuccess: (email) => toast.success(`验证邮件已发送到 ${email}`),
+    onSendError: () => toast.error('发送失败'),
+    onAlreadyVerified: () => navigate('/community')
+  })
+
+  return (
+    <div>
+      {isAlreadyVerified ? (
+        <p>邮箱已验证，正在跳转...</p>
+      ) : (
+        <>
+          <button onClick={resendVerification} disabled={isLoading || isCountingDown}>
+            {isCountingDown ? `${countdown}s 后重试` : '重新发送'}
+          </button>
+          <button onClick={changeEmail}>使用其他邮箱</button>
+        </>
+      )}
+    </div>
   )
 }
 ```
 
-### 认证状态同步
+## 服务层
 
-新用户登录后，使用 `setupCompanionTeam` 设置伴生组织和团队：
+### callbackService
+
+处理各种认证回调（OAuth、邮箱验证、删除用户等）：
 
 ```typescript
-import { setupCompanionTeam } from "@choiceform/shared-auth"
-
-// 在认证成功后调用
-setupCompanionTeam(auth, token, {
-  isNewUser: searchParams.get("isNew") === "true",
-  onComplete: () => {
-    // 刷新 session
-  },
+import { createCallbackService } from "@choiceform/shared-auth"
+
+const callbackService = createCallbackService(auth, {
+  lang: 'us',
+  defaultRedirect: '/',
+  signInPath: '/sign-in',
+  linkExpiredPath: '/auth/link-expired',
+  deleteSuccessPath: '/auth/delete-success',
 })
-```
 
-## API
+// 处理 OAuth 回调
+const result = await callbackService.handleOAuthCallback(token, isNewUser)
 
-### `initAuth(config)`
+// 处理邮箱验证回调
+const result = await callbackService.handleEmailVerificationCallback(token)
 
-快速初始化（使用默认配置）。
+// 处理删除用户回调
+const result = await callbackService.handleDeleteUserCallback(token, userEmail)
 
-| 参数 | 类型 | 说明 |
-|------|------|------|
-| baseURL | string | OneAuth API 地址 |
-| tokenStorageKey | string | localStorage key（默认 `auth-token`） |
-| plugins | BetterAuthPlugin[] | Better Auth 插件 |
+// 统一处理入口
+const result = await callbackService.handleCallback(type, token, { isNewUser, userEmail, invitationId })
+```
 
-### `createAuth(config)`
+### authService
 
-创建认证实例（完整配置）。
+业务逻辑封装：
 
-### AuthInstance
+```typescript
+// OAuth 登录
+await auth.authService.signInWithOAuth("github", callbackURL, newUserCallbackURL, errorCallbackURL)
 
-| 属性 | 说明 |
-|------|------|
-| authStore | Legend State store |
-| authActions | 认证操作（signIn, signOut 等） |
-| authApi | 认证 API |
-| organizationApi | 组织 API |
-| teamApi | 团队 API |
-| tokenStorage | Token 存储工具 |
+// Magic Link 登录
+await auth.authService.signInWithMagicLink(email, callbackURL, name, newUserCallbackURL)
 
-### 工具方法
+// 邮箱密码登录
+const result = await auth.authService.signInWithEmail(email, password)
 
-```typescript
-// 获取用户
-const user = auth.getCurrentUser()
-const userId = auth.getCurrentUserId()
+// 邮箱密码注册
+const result = await auth.authService.signUpWithEmail(email, password, name, callbackURL)
 
-// 认证状态
-const authenticated = auth.isAuthenticated()
-const loading = auth.isLoading()
-const loaded = auth.isLoaded()
+// 登出
+await auth.authService.signOut("/sign-in")
 
-// 等待认证完成
-await auth.waitForAuth()
+// 删除账户
+await auth.authService.deleteUser(callbackURL, password)
 
-// Token
-const token = auth.getAuthTokenSync()
-const headers = auth.getAuthHeadersSync()
+// 使用 Token 获取 Session
+await auth.authService.fetchAndSetSession(token)
 ```
 
-## 类型
+## 工具函数
 
 ```typescript
-import type {
-  SessionUser,
-  AuthState,
-  AuthConfig,
-  Organization,
-  Team,
-  Member,
+import {
+  // 验证
+  isValidEmail,
+  
+  // 错误解析
+  parseAuthError,
+  isTokenExpiredError,
+  AUTH_ERROR_CODES,
+  
+  // URL 工具
+  getNameFromEmail,
+  buildAuthUrl,
+  buildAuthPath,
+  clearAuthParams,
+  
+  // 用户映射
+  extractSessionUser,
 } from "@choiceform/shared-auth"
-```
-
-### SessionUser
 
-```typescript
-interface SessionUser {
-  id: string
-  email: string
-  name: string
-  image?: string
-  metadata?: { color?: string }
-  inherentOrganizationId?: string  // 伴生组织
-  inherentTeamId?: string          // 伴生团队
-  activeOrganizationId?: string
-  activeTeamId?: string
+// 验证邮箱
+if (isValidEmail(email)) {
   // ...
 }
+
+// 解析错误
+const { code, message, isKnownError } = parseAuthError(error)
+
+// 检查 token 是否过期
+if (isTokenExpiredError(error)) {
+  // 重新登录
+}
+
+// 构建 URL
+const url = buildAuthPath('/verify-email', { lang: 'us', email })
 ```
 
-## 响应式状态
+## Store Layer
+
+### authStore (Legend State Observable)
+
+响应式状态，可在 React 组件中使用：
 
 ```typescript
 import { use$ } from "@legendapp/state/react"
-import { auth } from "./lib/auth"
 
-function Profile() {
+function MyComponent() {
   const user = use$(auth.authStore.user)
-  const loading = use$(auth.authStore.loading)
-
-  if (loading) return <Loading />
-  if (!user) return <SignIn />
-
-  return <div>Hello, {user.name}</div>
+  const isAuthenticated = use$(auth.authStore.isAuthenticated)
+  const error = use$(auth.authStore.error)
+  
+  // Computed 状态
+  const isReady = use$(auth.authComputed.isReady)
+  const activeOrganizationId = use$(auth.authComputed.activeOrganizationId)
 }
 ```
 
-## 更新日志
+### storeActions
 
-### v0.2.0
+状态管理：
 
-- 服务器地址更换为 `https://oneauth.choiceform.io`
-- 伴生组织/团队改从 session 获取（`inherentOrganizationId`、`inherentTeamId`）
-- 新增 `onboard` API、Magic Link 支持
-- 移除 UI 组件（`AuthSync`、`ProtectedRoute`、`SignInPage`），由业务端实现
-- 代码清理和优化
+```typescript
+// 读取
+auth.storeActions.getUser()
+auth.storeActions.getUserId()
+auth.storeActions.isAuthenticated()
+auth.storeActions.isLoading()
+auth.storeActions.isLoaded()
+
+// 更新
+auth.storeActions.setUser(user)
+auth.storeActions.updateUser({ name: "New Name" })
+auth.storeActions.setLoading(true)
+auth.storeActions.setError("Error message")
+auth.storeActions.clearAuth()
+
+// Active 状态
+auth.storeActions.setActiveOrganizationId(orgId)
+auth.storeActions.setActiveTeamId(teamId)
+```
 
-### v0.1.x
+## 目录结构
 
-- 初始版本
+```
+src/
+├── api/                    # API Layer
+│   ├── client.ts           # HTTP 客户端
+│   ├── auth-api.ts         # 认证 API
+│   ├── organization-api.ts
+│   └── team-api.ts
+├── services/               # Service Layer
+│   ├── auth-service.ts     # 认证业务逻辑
+│   ├── callback-service.ts # 回调处理
+│   └── companion-team.ts   # 伴生团队设置
+├── store/                  # Store Layer
+│   ├── state.ts            # 状态定义
+│   ├── actions.ts          # 状态操作
+│   ├── computed.ts         # 计算属性
+│   └── utils.ts            # 工具函数
+├── hooks/                  # React Hooks
+│   ├── use-auth-init.ts
+│   ├── use-auth-sync.ts
+│   ├── use-protected-route.ts
+│   └── use-email-verification.ts
+├── utils/                  # 工具函数
+│   ├── auth-utils.ts       # 认证工具
+│   ├── user-mapper.ts
+│   └── env.ts
+├── types/                  # 类型定义
+├── lib/                    # Better Auth 客户端
+├── core.ts                 # 核心入口
+├── init.ts                 # 快速初始化
+├── config.ts               # 默认配置
+└── index.ts                # 导出入口
+```
 
-## License
+## 类型导出
 
-MIT
+```typescript
+import type {
+  // 核心
+  AuthInstance,
+  AuthState,
+  SessionUser,
+  
+  // 服务
+  AuthService,
+  CallbackService,
+  CallbackType,
+  CallbackResult,
+  
+  // Hooks
+  UseAuthSyncConfig,
+  UseProtectedRouteConfig,
+  UseProtectedRouteResult,
+  ProtectionStatus,
+  UseEmailVerificationConfig,
+  UseEmailVerificationResult,
+  
+  // 组织
+  Organization,
+  Member,
+  MemberWithUser,
+  Invitation,
+  MemberRole,
+  
+  // 团队
+  Team,
+  TeamMember,
+  
+  // 工具
+  AuthErrorCode,
+  ParsedAuthError,
+} from "@choiceform/shared-auth"
+```

package/dist/__tests__/auth-utils.test.d.ts

@@ -0,0 +1,5 @@
+/**
+ * 工具函数测试
+ */
+export {};
+//# sourceMappingURL=auth-utils.test.d.ts.map

package/dist/__tests__/auth-utils.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth-utils.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/auth-utils.test.ts"],"names":[],"mappings":"AAAA;;GAEG"}

package/dist/__tests__/auth-utils.test.js

@@ -0,0 +1,96 @@
+/**
+ * 工具函数测试
+ */
+import { describe, it, expect } from "vitest";
+import { isValidEmail, parseAuthError, isTokenExpiredError, getNameFromEmail, buildAuthPath, AUTH_ERROR_CODES, } from "../utils/auth-utils";
+describe("isValidEmail", () => {
+    it("应该验证有效的邮箱", () => {
+        expect(isValidEmail("test@example.com")).toBe(true);
+        expect(isValidEmail("user.name@domain.co")).toBe(true);
+        expect(isValidEmail("user+tag@example.org")).toBe(true);
+    });
+    it("应该拒绝无效的邮箱", () => {
+        expect(isValidEmail("")).toBe(false);
+        expect(isValidEmail("invalid")).toBe(false);
+        expect(isValidEmail("@example.com")).toBe(false);
+        expect(isValidEmail("test@")).toBe(false);
+        expect(isValidEmail("test@.com")).toBe(false);
+        expect(isValidEmail("test @example.com")).toBe(false);
+    });
+});
+describe("parseAuthError", () => {
+    it("应该解析 JSON 格式的错误", () => {
+        const error = JSON.stringify({ code: "PASSWORD_TOO_SHORT", message: "Password too short" });
+        const result = parseAuthError(error);
+        expect(result.code).toBe("PASSWORD_TOO_SHORT");
+        expect(result.isKnownError).toBe(true);
+    });
+    it("应该处理包含已知错误代码的字符串", () => {
+        const result = parseAuthError("Error: INVALID_EMAIL_OR_PASSWORD");
+        expect(result.code).toBe("INVALID_EMAIL_OR_PASSWORD");
+        expect(result.isKnownError).toBe(true);
+    });
+    it("应该处理未知错误", () => {
+        const result = parseAuthError("Some unknown error");
+        expect(result.code).toBeNull();
+        expect(result.isKnownError).toBe(false);
+        expect(result.message).toBe("Some unknown error");
+    });
+    it("应该处理 null 输入", () => {
+        const result = parseAuthError(null);
+        expect(result.code).toBeNull();
+        expect(result.message).toBe("");
+        expect(result.isKnownError).toBe(false);
+    });
+    it("应该识别所有已知的错误代码", () => {
+        for (const code of AUTH_ERROR_CODES) {
+            const error = JSON.stringify({ code, message: "test" });
+            const result = parseAuthError(error);
+            expect(result.code).toBe(code);
+            expect(result.isKnownError).toBe(true);
+        }
+    });
+});
+describe("isTokenExpiredError", () => {
+    it("应该识别 INVALID_TOKEN 错误", () => {
+        expect(isTokenExpiredError(JSON.stringify({ code: "INVALID_TOKEN" }))).toBe(true);
+    });
+    it("应该识别 SESSION_EXPIRED 错误", () => {
+        expect(isTokenExpiredError(JSON.stringify({ code: "SESSION_EXPIRED" }))).toBe(true);
+    });
+    it("应该识别包含 expired 的消息", () => {
+        expect(isTokenExpiredError("Token has expired")).toBe(true);
+    });
+    it("应该拒绝非过期错误", () => {
+        expect(isTokenExpiredError("Password too short")).toBe(false);
+        expect(isTokenExpiredError(null)).toBe(false);
+    });
+    it("应该接受 ParsedAuthError 对象", () => {
+        expect(isTokenExpiredError({ code: "INVALID_TOKEN", message: "", isKnownError: true })).toBe(true);
+        expect(isTokenExpiredError({ code: null, message: "expired", isKnownError: false })).toBe(true);
+    });
+});
+describe("getNameFromEmail", () => {
+    it("应该从邮箱中提取名称", () => {
+        expect(getNameFromEmail("john.doe@example.com")).toBe("john.doe");
+        expect(getNameFromEmail("user@domain.com")).toBe("user");
+        expect(getNameFromEmail("test+tag@example.org")).toBe("test+tag");
+    });
+    it("应该处理空字符串", () => {
+        expect(getNameFromEmail("")).toBe("");
+    });
+});
+describe("buildAuthPath", () => {
+    it("应该构建带参数的路径", () => {
+        const path = buildAuthPath("/sign-in", { lang: "us", email: "test@example.com" });
+        expect(path).toBe("/sign-in?lang=us&email=test%40example.com");
+    });
+    it("应该忽略 null 和 undefined 参数", () => {
+        const path = buildAuthPath("/sign-in", { lang: "us", email: null, name: undefined });
+        expect(path).toBe("/sign-in?lang=us");
+    });
+    it("应该返回无参数的路径", () => {
+        const path = buildAuthPath("/sign-in", {});
+        expect(path).toBe("/sign-in");
+    });
+});

package/dist/__tests__/store.test.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Store 测试
+ */
+export {};
+//# sourceMappingURL=store.test.d.ts.map

package/dist/__tests__/store.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/store.test.ts"],"names":[],"mappings":"AAAA;;GAEG"}