@bagelink/auth 1.4.169 → 1.4.174

package/README.md

@@ -1,186 +1,330 @@
 # @bagelink/auth
 
-A framework-agnostic authentication composable with Vue support.
+A user-centric authentication library with Vue support. Handles both person and entity accounts seamlessly.
 
 ## Features
 
-- Framework-agnostic reactivity system
-- Automatic Vue integration
-- TypeScript support
-- Complete authentication flow (login, signup, password recovery, etc.)
-- Error handling
-- User management
-- Event listeners for authentication state changes
+- 🎯 **User-Centric Design** - Access user data directly, not buried in account objects
+- 🔄 **Multi-Account Support** - Works with person, entity, and service accounts
+- 🛡️ **Type-Safe** - Full TypeScript support
+- ⚡ **Vue Integration** - Reactive refs with Vue 3 composables
+- 🔐 **Complete Auth Flow** - Login, signup, password management, email verification
+- 📡 **Session Management** - View, refresh, and revoke sessions
+- 🎪 **Event System** - Listen to authentication state changes
+- 🌐 **Framework Agnostic** - Core auth logic works anywhere
 
 ## Installation
 
 ```bash
+pnpm add @bagelink/auth
+# or
+npm install @bagelink/auth
+# or
 bun add @bagelink/auth
 ```
 
-## Usage
+## Quick Start
 
-### Basic Setup
+### 1. Initialize Auth
 
 ```typescript
-import { initAuth, AuthState } from '@bagelink/auth'
+import { initAuth } from '@bagelink/auth'
+import axios from 'axios'
 
-// Initialize with axios instance
 const auth = initAuth({ 
-  axios: axiosInstance,
+  axios: axios,
   baseURL: 'https://api.example.com'
 })
 
-// Add event listeners for authentication state changes
+// Listen to auth events
 auth.on(AuthState.LOGIN, () => {
   console.log('User logged in!')
-  // Redirect to dashboard, update UI, etc.
 })
+```
 
-auth.on(AuthState.LOGOUT, () => {
-  console.log('User logged out!')
-  // Redirect to login page, clear sensitive data, etc.
+### 2. Use in Vue Components
+
+```vue
+<script setup lang="ts">
+import { useAuth } from '@bagelink/auth'
+
+const { 
+  user,           // Primary state - use this!
+  getIsLoggedIn,
+  login,
+  logout 
+} = useAuth()
+
+const handleLogin = async () => {
+  await login({ 
+    email: 'user@example.com', 
+    password: 'password' 
+  })
+}
+</script>
+
+<template>
+  <div v-if="user">
+    <h1>Welcome, {{ user.name }}!</h1>
+    <p>Email: {{ user.email }}</p>
+    <button @click="logout">Logout</button>
+  </div>
+  <div v-else>
+    <button @click="handleLogin">Login</button>
+  </div>
+</template>
+```
+
+## Core Concepts
+
+### The `user` Object
+
+The `user` is a **computed ref** that provides a unified interface for both person and entity accounts:
+
+```typescript
+const { user } = useAuth()
+
+// Available for all account types
+user.value?.id          // Person ID or Entity ID
+user.value?.name        // Display name
+user.value?.email       // Email address
+user.value?.type        // 'person', 'entity', or 'service'
+user.value?.isActive    // Is account active
+user.value?.isVerified  // Is account verified
+
+// Person-specific
+user.value?.roles       // User roles (e.g., ['admin', 'user'])
+
+// Entity-specific
+user.value?.entityType  // Entity type (e.g., 'company', 'organization')
+user.value?.metadata    // Additional entity metadata
+```
+
+### Account Info (Advanced)
+
+For authentication-specific data, use `accountInfo`:
+
+```typescript
+const { accountInfo } = useAuth()
+
+accountInfo.value?.authentication_methods  // Auth methods
+accountInfo.value?.last_login              // Last login timestamp
+accountInfo.value?.person                  // Raw person data
+accountInfo.value?.entity                  // Raw entity data
+```
+
+## API Reference
+
+### State
+
+```typescript
+const {
+  user,        // Computed<User | null> - Primary state
+  accountInfo, // Ref<AccountInfo | null> - Full account data
+} = useAuth()
+```
+
+### Getters
+
+```typescript
+const {
+  getFullName,      // () => string
+  getIsLoggedIn,    // () => boolean
+  getEmail,         // () => string
+  getRoles,         // () => string[]
+  getAccountType,   // () => 'person' | 'entity' | 'service'
+  isPersonAccount,  // () => boolean
+  isEntityAccount,  // () => boolean
+} = useAuth()
+```
+
+### Authentication
+
+```typescript
+// Login
+await login({ email: 'user@example.com', password: 'password' })
+
+// Signup
+await signup({ 
+  email: 'user@example.com',
+  first_name: 'John',
+  last_name: 'Doe',
+  password: 'password',
+  confirmPassword: 'password'
 })
+
+// Logout
+await logout()
+
+// Check auth status
+const isAuthenticated = await checkAuth()
+
+// Refresh session
+await refreshSession()
 ```
 
-### Vue Integration
+### Password Management
 
 ```typescript
-// In your main.ts
-import { createApp } from 'vue'
-import { initAuth } from '@bagelink/auth'
+// Change password (requires current password)
+await changePassword({
+  current_password: 'oldPassword',
+  new_password: 'newPassword',
+  confirmNewPassword: 'newPassword'
+})
 
-const app = createApp(App)
+// Forgot password
+await forgotPassword('user@example.com')
 
-// Initialize auth
-const auth = initAuth({ 
-  axios: axiosInstance,
-  errorHandler: (error) => console.error(error)
+// Verify reset token
+await verifyResetToken(token)
+
+// Reset password with token
+await resetPassword(token, 'newPassword')
+```
+
+### Email Verification
+
+```typescript
+// Send verification email
+await sendVerification('user@example.com')
+
+// Verify email with token
+await verifyEmail(token)
+```
+
+### Profile Management
+
+```typescript
+// Update profile
+await updateProfile({
+  first_name: 'Jane',
+  last_name: 'Smith',
+  email: 'jane@example.com'
 })
 
-// Use as a plugin
-app.use(auth)
+// Delete current user account
+await deleteCurrentUser()
+```
 
-// In your components
-import { useAuth } from '@bagelink/auth'
+### Session Management
 
-export default {
-  setup() {
-    const { login, currentUser, getIsLoggedIn } = useAuth()
-    
-    // Use auth methods
-    const handleLogin = async () => {
-      await login({
-        email: 'user@example.com',
-        password: 'password'
-      })
-    }
-
-    return {
-      currentUser,
-      getIsLoggedIn,
-      handleLogin
-    }
-  }
-}
+```typescript
+// Get active sessions
+const { data } = await getSessions()
+const sessions = data.sessions
+
+// Revoke specific session
+await revokeSession(sessionToken)
+
+// Revoke all sessions
+await revokeAllSessions()
+```
+
+### Admin Actions
+
+```typescript
+// Activate/deactivate accounts
+await activateAccount(accountId)
+await deactivateAccount(accountId)
+
+// Delete account
+await deleteAccount(accountId)
 ```
 
-### Event Listeners
+## Event System
 
-You can listen to authentication state changes using the event system:
+Listen to authentication state changes:
 
 ```typescript
 import { initAuth, AuthState } from '@bagelink/auth'
 
-const auth = initAuth({ 
-  axios: axiosInstance,
-  baseURL: 'https://api.example.com'
-})
+const auth = initAuth({ axios })
 
-// Listen to login events
+// Login
 auth.on(AuthState.LOGIN, () => {
-  router.push('/dashboard')
+  console.log('User logged in')
 })
 
-// Listen to logout events
+// Logout
 auth.on(AuthState.LOGOUT, () => {
-  router.push('/login')
+  console.log('User logged out')
 })
 
-// Listen to signup events
+// Signup
 auth.on(AuthState.SIGNUP, () => {
-  router.push('/welcome')
+  console.log('User signed up')
+})
+
+// Password changed
+auth.on(AuthState.PASSWORD_CHANGE, () => {
+  console.log('Password changed')
 })
 
-// Listen to password reset events
+// Password reset
 auth.on(AuthState.PASSWORD_RESET, () => {
-  console.log('Password has been reset')
+  console.log('Password reset')
 })
 
-// Listen to profile update events
+// Profile updated
 auth.on(AuthState.PROFILE_UPDATE, () => {
-  console.log('Profile updated successfully')
+  console.log('Profile updated')
 })
 
-// Listen to auth check events (when user is authenticated)
+// Auth check completed
 auth.on(AuthState.AUTH_CHECK, () => {
-  console.log('User authentication verified')
+  console.log('Auth verified')
 })
-```
-
-#### Event Methods
 
-- `auth.on(event, handler)`: Add an event listener
-- `auth.off(event, handler)`: Remove a specific event listener
-- `auth.removeAllListeners(event?)`: Remove all listeners for an event (or all events if no event specified)
-
-#### Available Events
+// Email verified
+auth.on(AuthState.EMAIL_VERIFIED, () => {
+  console.log('Email verified')
+})
 
-- `AuthState.LOGIN`: Fired when user successfully logs in
-- `AuthState.LOGOUT`: Fired when user logs out
-- `AuthState.SIGNUP`: Fired when user successfully signs up
-- `AuthState.PASSWORD_RESET`: Fired when password is reset or updated
-- `AuthState.PROFILE_UPDATE`: Fired when user profile is updated
-- `AuthState.AUTH_CHECK`: Fired when user authentication is verified
+// Session refreshed
+auth.on(AuthState.SESSION_REFRESH, () => {
+  console.log('Session refreshed')
+})
+```
 
-### Vanilla JavaScript
+### Event Methods
 
 ```typescript
-import { initAuth } from '@bagelink/auth'
+// Add listener
+auth.on(AuthState.LOGIN, handler)
 
-const auth = initAuth({ 
-  axios: axiosInstance,
-  baseURL: 'https://api.example.com'
-})
-
-const { login, currentUser, getIsLoggedIn } = auth.useAuth()
-```
+// Remove listener
+auth.off(AuthState.LOGIN, handler)
 
-## API
+// Remove all listeners for an event
+auth.removeAllListeners(AuthState.LOGIN)
 
-### State
+// Remove all listeners
+auth.removeAllListeners()
+```
 
-- `currentUser`: Current user information
-- `passwordForm`: Password update form state
+## TypeScript Support
 
-### Getters
+Full TypeScript support with exported types:
 
-- `getFullName()`: Get user's full name
-- `getIsLoggedIn()`: Check if user is logged in
+```typescript
+import type { 
+  User,
+  AccountInfo,
+  PersonInfo,
+  EntityInfo,
+  RegisterRequest,
+  UpdateAccountRequest,
+  AuthenticationResponse,
+  SessionInfo,
+  // ... and more
+} from '@bagelink/auth'
+```
 
-### Actions
+## Migration
 
-- `login(credentials)`: Login with email and password
-- `logout()`: Logout current user
-- `checkAuth()`: Check authentication status
-- `signup(user)`: Register new user
-- `recoverPassword(email)`: Request password recovery
-- `resetPassword(form)`: Reset password
-- `updatePassword()`: Update current user's password
-- `updateProfile(user)`: Update user profile
-- `toggleUserStatus(userId, isActive)`: Toggle user active status
-- `deleteUser(userId)`: Delete user
+Upgrading from an older version? See [MIGRATION.md](./MIGRATION.md) for detailed migration instructions.
 
 ## License
 
-MIT 
+MIT