@choiceform/shared-auth 0.1.18 → 0.1.20

package/README.md

@@ -1,55 +1,140 @@
 # @choiceform/shared-auth
 
-基于 Better Auth + Legend State 的共享认证库。
+A shared authentication library based on Better Auth + Legend State.
 
-## 架构设计
+## Architecture
 
 ```
 ┌─────────────────────────────────────────────────────────────┐
-│                        createAuth()                          │
-│                         (core.ts)                            │
+│                    createAuth() / initAuth()                │
+│                          (core.ts)                          │
 ├─────────────────────────────────────────────────────────────┤
-│                                                              │
-│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────────┐ │
-│  │  Store   │  │ Service  │  │   API    │  │    Hooks     │ │
-│  │  Layer   │  │  Layer   │  │  Layer   │  │    Layer     │ │
-│  │          │  │          │  │          │  │              │ │
-│  │authStore │  │authServ. │  │apiClient │  │useAuthSync   │ │
-│  │storeAct. │  │callback  │  │authApi   │  │useProtected  │ │
-│  │computed  │  │companion │  │orgApi    │  │useEmailVerif │ │
-│  └──────────┘  └──────────┘  └──────────┘  └──────────────┘ │
-│                                                              │
+│                                                             │
+│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌─────────────┐  │
+│  │  Store   │  │ Service  │  │   API    │  │   Hooks     │  │
+│  │  Layer   │  │  Layer   │  │  Layer   │  │   Layer     │  │
+│  │          │  │          │  │          │  │             │  │
+│  │authStore │  │authServ. │  │apiClient │  │useAuthSync  │  │
+│  │storeAct. │  │callback  │  │authApi   │  │useProtected │  │
+│  │computed  │  │companion │  │orgApi    │  │useEmailVer. │  │
+│  └──────────┘  └──────────┘  └──────────┘  └─────────────┘  │
+│                                                             │
 └─────────────────────────────────────────────────────────────┘
 ```
 
-### 四层架构
+### Four-Layer Architecture
 
-| 层级 | 职责 | 文件 |
-|------|------|------|
-| **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` |
+| Layer | Responsibility | Files |
+|-------|----------------|-------|
+| **Store Layer** | Reactive state management | `store/state.ts`, `store/actions.ts`, `store/computed.ts`, `store/utils.ts` |
+| **Service Layer** | Business logic | `services/auth-service.ts`, `services/callback-service.ts`, `services/companion-team.ts` |
+| **API Layer** | HTTP requests | `api/client.ts`, `api/auth-api.ts`, `api/organization-api.ts`, `api/team-api.ts` |
+| **Hooks Layer** | React-specific | `hooks/use-auth-sync.ts`, `hooks/use-protected-route.ts`, `hooks/use-email-verification.ts` |
 
-## 快速开始
+## Installation
+
+```bash
+pnpm add @choiceform/shared-auth
+```
+
+### Peer Dependencies
+
+```json
+{
+  "@legendapp/state": "v3.0.0-beta.30",
+  "better-auth": "^1.4.4",
+  "react": ">=18.0.0",
+  "react-dom": ">=18.0.0"
+}
+```
+
+## Quick Start
+
+### Option 1: initAuth (Recommended)
+
+Quick initialization with default configuration, automatically includes `magicLinkClient` and `organizationClient` plugins:
 
 ```typescript
 import { initAuth } from "@choiceform/shared-auth"
 
-// 初始化
 const auth = initAuth({
   baseURL: "https://api.example.com",
+  // Optional configuration
+  tokenStorageKey: "auth-token",        // localStorage key, defaults to "auth-token"
+  skipTokenCleanupOnError: false,       // Set to true for development
+})
+
+export { auth }
+```
+
+### Option 2: createAuth (Custom Configuration)
+
+Use when you need custom Better Auth plugins:
+
+```typescript
+import { createAuth } from "@choiceform/shared-auth"
+import { magicLinkClient, organizationClient } from "better-auth/client/plugins"
+
+const auth = createAuth({
+  baseURL: "https://api.example.com",
+  plugins: [
+    magicLinkClient(),
+    organizationClient({ teams: { enabled: true } }),
+    // Other plugins...
+  ],
+  tokenStorageKey: "auth-token",
 })
 
-// 导出供全局使用
 export { auth }
 ```
 
-## Hooks（推荐使用）
+## AuthInstance API
+
+The instance returned by `createAuth()` / `initAuth()` includes:
+
+```typescript
+const auth = initAuth({ baseURL: "..." })
+
+// API Layer
+auth.apiClient          // HTTP client
+auth.authApi            // Auth API
+auth.organizationApi    // Organization API
+auth.teamApi            // Team API
+
+// Store Layer
+auth.authStore          // Legend State Observable
+auth.authComputed       // Computed properties
+auth.tokenStorage       // Token storage
+auth.storeActions       // State actions
+
+// Service Layer
+auth.authService        // Auth business logic
+
+// Active State Management
+auth.setActiveOrganization(request)
+auth.setActiveTeam(request)
+auth.setActiveOrganizationAndTeam(orgId, teamId)
+
+// Shortcut Methods
+auth.getCurrentUser()   // Get current user
+auth.getCurrentUserId() // Get current user ID
+auth.isAuthenticated()  // Check if authenticated
+auth.isLoading()        // Check if loading
+auth.isLoaded()         // Check if loaded
+auth.getAuthToken()     // Get token
+auth.getAuthHeaders()   // Get auth headers
+auth.waitForAuth()      // Wait for auth to complete
+auth.userManager        // User manager
+
+// Better Auth Client (Advanced)
+auth.authClient         // Raw Better Auth client
+```
+
+## Hooks (Recommended)
 
 ### useAuthSync
 
-认证状态同步，替代手动同步 Better Auth session：
+Sync authentication state, replaces manual Better Auth session sync:
 
 ```typescript
 import { useAuthSync } from "@choiceform/shared-auth"
@@ -71,7 +156,7 @@ function App() {
 
 ### useProtectedRoute
 
-路由保护，检查认证状态和邮箱验证：
+Route protection, checks authentication status and email verification:
 
 ```typescript
 import { useProtectedRoute } from "@choiceform/shared-auth"
@@ -103,7 +188,7 @@ function ProtectedRoute({ children }) {
 
 ### useEmailVerification
 
-邮箱验证流程：
+Email verification flow:
 
 ```typescript
 import { useEmailVerification } from "@choiceform/shared-auth"
@@ -122,21 +207,21 @@ function VerifyEmailPage({ email, lang }) {
     email,
     lang,
     onRedirect: (path) => navigate(path),
-    onSendSuccess: (email) => toast.success(`验证邮件已发送到 ${email}`),
-    onSendError: () => toast.error('发送失败'),
+    onSendSuccess: (email) => toast.success(`Verification email sent to ${email}`),
+    onSendError: () => toast.error('Failed to send'),
     onAlreadyVerified: () => navigate('/community')
   })
 
   return (
     <div>
       {isAlreadyVerified ? (
-        <p>邮箱已验证，正在跳转...</p>
+        <p>Email verified, redirecting...</p>
       ) : (
         <>
           <button onClick={resendVerification} disabled={isLoading || isCountingDown}>
-            {isCountingDown ? `${countdown}s 后重试` : '重新发送'}
+            {isCountingDown ? `Retry in ${countdown}s` : 'Resend'}
           </button>
-          <button onClick={changeEmail}>使用其他邮箱</button>
+          <button onClick={changeEmail}>Use different email</button>
         </>
       )}
     </div>
@@ -144,107 +229,95 @@ function VerifyEmailPage({ email, lang }) {
 }
 ```
 
-## 服务层
+### useAuthInit
 
-### callbackService
-
-处理各种认证回调（OAuth、邮箱验证、删除用户等）：
+Initialize authentication state:
 
 ```typescript
-import { createCallbackService } from "@choiceform/shared-auth"
-
-const callbackService = createCallbackService(auth, {
-  lang: 'us',
-  defaultRedirect: '/',
-  signInPath: '/sign-in',
-  linkExpiredPath: '/auth/link-expired',
-  deleteSuccessPath: '/auth/delete-success',
-})
-
-// 处理 OAuth 回调
-const result = await callbackService.handleOAuthCallback(token, isNewUser)
+import { useAuthInit, initializeAuth } from "@choiceform/shared-auth"
 
-// 处理邮箱验证回调
-const result = await callbackService.handleEmailVerificationCallback(token)
-
-// 处理删除用户回调
-const result = await callbackService.handleDeleteUserCallback(token, userEmail)
+// Hook approach
+function App() {
+  useAuthInit(auth)
+  return <YourApp />
+}
 
-// 统一处理入口
-const result = await callbackService.handleCallback(type, token, { isNewUser, userEmail, invitationId })
+// Or manual call
+await initializeAuth(auth)
 ```
 
+## Service Layer
+
 ### authService
 
-业务逻辑封装：
+Auth business logic wrapper:
 
 ```typescript
-// OAuth 登录
+// OAuth sign in
 await auth.authService.signInWithOAuth("github", callbackURL, newUserCallbackURL, errorCallbackURL)
 
-// Magic Link 登录
+// Magic Link sign in
 await auth.authService.signInWithMagicLink(email, callbackURL, name, newUserCallbackURL)
 
-// 邮箱密码登录
+// Email/password sign in
 const result = await auth.authService.signInWithEmail(email, password)
 
-// 邮箱密码注册
+// Email/password sign up
 const result = await auth.authService.signUpWithEmail(email, password, name, callbackURL)
 
-// 登出
+// Sign out
 await auth.authService.signOut("/sign-in")
 
-// 删除账户
+// Delete account
 await auth.authService.deleteUser(callbackURL, password)
 
-// 使用 Token 获取 Session
+// Fetch session with token
 await auth.authService.fetchAndSetSession(token)
 ```
 
-## 工具函数
+### callbackService
+
+Handle various auth callbacks (OAuth, email verification, user deletion, etc.):
 
 ```typescript
-import {
-  // 验证
-  isValidEmail,
-  
-  // 错误解析
-  parseAuthError,
-  isTokenExpiredError,
-  AUTH_ERROR_CODES,
-  
-  // URL 工具
-  getNameFromEmail,
-  buildAuthUrl,
-  buildAuthPath,
-  clearAuthParams,
-  
-  // 用户映射
-  extractSessionUser,
-} from "@choiceform/shared-auth"
+import { createCallbackService } from "@choiceform/shared-auth"
 
-// 验证邮箱
-if (isValidEmail(email)) {
-  // ...
-}
+const callbackService = createCallbackService(auth, {
+  lang: 'us',
+  defaultRedirect: '/',
+  signInPath: '/sign-in',
+  linkExpiredPath: '/auth/link-expired',
+  deleteSuccessPath: '/auth/delete-success',
+})
 
-// 解析错误
-const { code, message, isKnownError } = parseAuthError(error)
+// Handle OAuth callback
+const result = await callbackService.handleOAuthCallback(token, isNewUser)
 
-// 检查 token 是否过期
-if (isTokenExpiredError(error)) {
-  // 重新登录
-}
+// Handle email verification callback
+const result = await callbackService.handleEmailVerificationCallback(token)
 
-// 构建 URL
-const url = buildAuthPath('/verify-email', { lang: 'us', email })
+// Handle delete user callback
+const result = await callbackService.handleDeleteUserCallback(token, userEmail)
+
+// Unified handler
+const result = await callbackService.handleCallback(type, token, { isNewUser, userEmail, invitationId })
+```
+
+### companionTeam
+
+Companion team setup:
+
+```typescript
+import { setupCompanionTeam } from "@choiceform/shared-auth"
+
+await setupCompanionTeam(auth, options)
 ```
 
 ## Store Layer
 
 ### authStore (Legend State Observable)
 
-响应式状态，可在 React 组件中使用：
+Reactive state, can be used in React components:
 
 ```typescript
 import { use$ } from "@legendapp/state/react"
@@ -252,9 +325,11 @@ import { use$ } from "@legendapp/state/react"
 function MyComponent() {
   const user = use$(auth.authStore.user)
   const isAuthenticated = use$(auth.authStore.isAuthenticated)
+  const loading = use$(auth.authStore.loading)
   const error = use$(auth.authStore.error)
-  
-  // Computed 状态
+  const isLoaded = use$(auth.authStore.isLoaded)
+
+  // Computed state
   const isReady = use$(auth.authComputed.isReady)
   const activeOrganizationId = use$(auth.authComputed.activeOrganizationId)
 }
@@ -262,99 +337,255 @@ function MyComponent() {
 
 ### storeActions
 
-状态管理：
+State management actions:
 
 ```typescript
-// 读取
+// Read
 auth.storeActions.getUser()
 auth.storeActions.getUserId()
 auth.storeActions.isAuthenticated()
 auth.storeActions.isLoading()
 auth.storeActions.isLoaded()
 
-// 更新
+// Update
 auth.storeActions.setUser(user)
 auth.storeActions.updateUser({ name: "New Name" })
 auth.storeActions.setLoading(true)
 auth.storeActions.setError("Error message")
 auth.storeActions.clearAuth()
+auth.storeActions.handleUnauthorized()
 
-// Active 状态
+// Active state
 auth.storeActions.setActiveOrganizationId(orgId)
 auth.storeActions.setActiveTeamId(teamId)
 ```
 
-## 目录结构
+### Store Utilities
+
+Standalone utility functions for non-component scenarios:
+
+```typescript
+import {
+  getCurrentUser,
+  getCurrentUserId,
+  isAuthenticated,
+  isLoading,
+  isLoaded,
+  waitForAuth,
+  getAuthToken,
+  getAuthTokenSync,
+  getAuthHeaders,
+  getAuthHeadersSync,
+  handle401Response,
+  createUserManager,
+} from "@choiceform/shared-auth"
+
+// Wait for auth to complete
+await waitForAuth(auth.authStore)
+
+// Get auth headers (sync)
+const headers = getAuthHeadersSync(auth.tokenStorage)
+
+// Handle 401 response
+handle401Response(response, auth.storeActions)
+```
+
+## Utilities
+
+```typescript
+import {
+  // Environment
+  getEnvVar,
+  getAuthBaseUrl,
+
+  // Validation
+  isValidEmail,
+
+  // Error parsing
+  parseAuthError,
+  isTokenExpiredError,
+  AUTH_ERROR_CODES,
+
+  // URL utilities
+  getNameFromEmail,
+  buildAuthUrl,
+  buildAuthPath,
+  clearAuthParams,
+
+  // User mapping
+  extractSessionUser,
+} from "@choiceform/shared-auth"
+
+// Validate email
+if (isValidEmail(email)) {
+  // ...
+}
+
+// Parse error
+const { code, message, isKnownError } = parseAuthError(error)
+
+// Check if token expired
+if (isTokenExpiredError(error)) {
+  // Re-authenticate
+}
+
+// Build URL
+const url = buildAuthPath('/verify-email', { lang: 'us', email })
+```
+
+## API Layer
+
+Low-level API access:
+
+```typescript
+import {
+  createApiClient,
+  createAuthApi,
+  createOrganizationApi,
+  createTeamApi,
+  parseErrorResponse,
+} from "@choiceform/shared-auth"
+
+// Use APIs directly
+const response = await auth.authApi.getSession()
+const orgs = await auth.organizationApi.listOrganizations()
+const teams = await auth.teamApi.listTeams()
+```
+
+## Directory Structure
 
 ```
 src/
 ├── api/                    # API Layer
-│   ├── client.ts           # HTTP 客户端
-│   ├── auth-api.ts         # 认证 API
-│   ├── organization-api.ts
-│   └── team-api.ts
+│   ├── client.ts           # HTTP client
+│   ├── auth-api.ts         # Auth API
+│   ├── organization-api.ts # Organization API
+│   ├── team-api.ts         # Team API
+│   └── index.ts
 ├── services/               # Service Layer
-│   ├── auth-service.ts     # 认证业务逻辑
-│   ├── callback-service.ts # 回调处理
-│   └── companion-team.ts   # 伴生团队设置
+│   ├── auth-service.ts     # Auth business logic
+│   ├── callback-service.ts # Callback handling
+│   ├── companion-team.ts   # Companion team setup
+│   └── index.ts
 ├── store/                  # Store Layer
-│   ├── state.ts            # 状态定义
-│   ├── actions.ts          # 状态操作
-│   ├── computed.ts         # 计算属性
-│   └── utils.ts            # 工具函数
+│   ├── state.ts            # State definition
+│   ├── actions.ts          # State actions
+│   ├── computed.ts         # Computed properties
+│   ├── utils.ts            # Utility functions
+│   └── index.ts
 ├── hooks/                  # React Hooks
-│   ├── use-auth-init.ts
-│   ├── use-auth-sync.ts
+│   ├── use-auth-init.ts    # Auth initialization
+│   ├── use-auth-sync.ts    # State sync
 │   ├── 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                # 导出入口
+│   ├── use-email-verification.ts
+│   └── index.ts
+├── utils/                  # Utilities
+│   ├── auth-utils.ts       # Auth utilities
+│   ├── user-mapper.ts      # User mapping
+│   ├── date.ts             # Date utilities
+│   ├── env.ts              # Environment variables
+│   └── index.ts
+├── types/                  # Type definitions
+│   ├── auth.ts
+│   ├── callback.ts
+│   ├── organization.ts
+│   ├── team.ts
+│   ├── user.ts
+│   └── index.ts
+├── lib/                    # Better Auth client
+│   └── auth-client.ts
+├── core.ts                 # Core entry (createAuth)
+├── init.ts                 # Quick init (initAuth)
+├── config.ts               # Default config
+└── index.ts                # Export entry
 ```
 
-## 类型导出
+## Type Exports
 
 ```typescript
 import type {
-  // 核心
+  // Core
   AuthInstance,
   AuthState,
+  AuthConfig,
   SessionUser,
-  
-  // 服务
+  SessionUserMetadata,
+  Session,
+
+  // Services
   AuthService,
+  AuthServiceConfig,
   CallbackService,
   CallbackType,
   CallbackResult,
-  
+  CallbackConfig,
+
   // Hooks
   UseAuthSyncConfig,
+  UseAuthSyncResult,
   UseProtectedRouteConfig,
   UseProtectedRouteResult,
   ProtectionStatus,
   UseEmailVerificationConfig,
   UseEmailVerificationResult,
-  
-  // 组织
+
+  // Organization
   Organization,
+  OrganizationMetadata,
+  FullOrganization,
+  CreateOrganizationRequest,
+  UpdateOrganizationRequest,
   Member,
   MemberWithUser,
-  Invitation,
   MemberRole,
-  
-  // 团队
+  Invitation,
+  InvitationDetail,
+  InvitationStatus,
+
+  // Team
   Team,
+  TeamMetadata,
   TeamMember,
-  
-  // 工具
+  CreateTeamRequest,
+  UpdateTeamRequest,
+
+  // API
+  ApiClient,
+  ApiClientConfig,
+  ApiResponse,
+  TokenStorage,
+  AuthApi,
+  OrganizationApi,
+  TeamApi,
+
+  // Store
+  StoreActions,
+
+  // Utilities
   AuthErrorCode,
   ParsedAuthError,
 } from "@choiceform/shared-auth"
 ```
+
+## Development
+
+```bash
+# Install dependencies
+pnpm install
+
+# Development mode
+pnpm dev
+
+# Build
+pnpm build
+
+# Test
+pnpm test
+
+# Watch tests
+pnpm test:watch
+```
+
+## License
+
+MIT