@bagelink/auth 1.4.171 → 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

package/dist/index.cjs

@@ -263,10 +263,52 @@ var AuthState = /* @__PURE__ */ ((AuthState2) => {
   AuthState2["SESSION_REFRESH"] = "session_refresh";
   return AuthState2;
 })(AuthState || {});
+function accountToUser(account) {
+  if (account === null) return null;
+  if (account.person !== void 0) {
+    return {
+      id: account.person.id,
+      accountId: account.id,
+      name: account.person.name,
+      email: account.person.email,
+      type: account.account_type,
+      roles: account.person.roles,
+      isActive: account.is_active,
+      isVerified: account.is_verified,
+      lastLogin: account.last_login
+    };
+  }
+  if (account.entity !== void 0) {
+    return {
+      id: account.entity.id,
+      accountId: account.id,
+      name: account.entity.name,
+      type: account.account_type,
+      isActive: account.is_active,
+      isVerified: account.is_verified,
+      lastLogin: account.last_login,
+      entityType: account.entity.type,
+      metadata: account.entity.metadata
+    };
+  }
+  const emailMethod = account.authentication_methods?.find(
+    (m) => m.type === "password" || m.type === "email_token"
+  );
+  return {
+    id: account.id,
+    accountId: account.id,
+    name: account.display_name,
+    email: emailMethod?.identifier,
+    type: account.account_type,
+    isActive: account.is_active,
+    isVerified: account.is_verified,
+    lastLogin: account.last_login
+  };
+}
 
 let authApi = null;
 let eventEmitter = null;
-const currentUser = vue.ref(null);
+const accountInfo = vue.ref(null);
 function initAuth({
   axios,
   baseURL
@@ -308,32 +350,33 @@ function useAuth() {
   }
   const api = authApi;
   const emitter = eventEmitter;
+  const user = vue.computed(() => accountToUser(accountInfo.value));
   const getFullName = () => {
-    const user = currentUser.value;
-    if (user === null) return "";
-    if (user.person !== void 0) return user.person.name;
-    return user.display_name ?? "";
+    return user.value?.name ?? "";
   };
   const getIsLoggedIn = () => {
-    const user = currentUser.value;
-    return user !== null && user.id.length > 0;
+    return user.value !== null;
   };
   const getEmail = () => {
-    const user = currentUser.value;
-    if (user === null) return "";
-    if (user.person?.email !== void 0) {
-      return user.person.email;
-    }
-    const emailMethod = user.authentication_methods?.find(
-      (m) => m.type === "password" || m.type === "email_token"
-    );
-    return emailMethod?.identifier ?? "";
+    return user.value?.email ?? "";
+  };
+  const getRoles = () => {
+    return user.value?.roles ?? [];
+  };
+  const getAccountType = () => {
+    return user.value?.type ?? "person";
+  };
+  const isPersonAccount = () => {
+    return user.value?.type === "person";
+  };
+  const isEntityAccount = () => {
+    return user.value?.type === "entity";
   };
   async function logout() {
     const logoutPromise = api.logout();
     await logoutPromise.catch(() => {
     });
-    currentUser.value = null;
+    accountInfo.value = null;
     emitter.emit(AuthState.LOGOUT);
   }
   async function login(credentials) {
@@ -350,26 +393,27 @@ function useAuth() {
   async function checkAuth() {
     try {
       const { data } = await api.getCurrentUser();
-      currentUser.value = data;
+      accountInfo.value = data;
       if (getIsLoggedIn()) {
         emitter.emit(AuthState.AUTH_CHECK);
       }
       return true;
     } catch {
-      currentUser.value = null;
+      accountInfo.value = null;
       return false;
     }
   }
-  async function signup(user) {
-    if (user.password && user.password !== user.confirmPassword) {
+  async function signup(newUser) {
+    const hasPassword = newUser.password !== void 0 && newUser.password.length > 0;
+    if (hasPassword && newUser.password !== newUser.confirmPassword) {
       throw new Error("Passwords do not match");
     }
     const { data } = await api.register({
-      email: user.email,
-      first_name: user.first_name,
-      last_name: user.last_name,
-      phone_number: user.phone_number,
-      password: user.password
+      email: newUser.email,
+      first_name: newUser.first_name,
+      last_name: newUser.last_name,
+      phone_number: newUser.phone_number,
+      password: newUser.password
     });
     if (data.success === true && data.requires_verification !== true) {
       await checkAuth();
@@ -399,7 +443,7 @@ function useAuth() {
   }
   async function updateProfile(updates) {
     const { data } = await api.updateCurrentUser(updates);
-    currentUser.value = data;
+    accountInfo.value = data;
     emitter.emit(AuthState.PROFILE_UPDATE);
   }
   async function activateAccount(accountId) {
@@ -413,7 +457,7 @@ function useAuth() {
   }
   async function deleteCurrentUser() {
     await api.deleteCurrentUser();
-    currentUser.value = null;
+    accountInfo.value = null;
   }
   async function sendVerification(email) {
     await api.sendVerification({ email });
@@ -428,7 +472,7 @@ function useAuth() {
     emitter.emit(AuthState.SESSION_REFRESH);
   }
   async function getSessions(accountId) {
-    const id = accountId ?? currentUser.value?.id;
+    const id = accountId ?? user.value?.accountId;
     if (id === void 0 || id === "") {
       throw new Error("No account ID available");
     }
@@ -438,19 +482,25 @@ function useAuth() {
     await api.revokeSession(sessionToken);
   }
   async function revokeAllSessions(accountId) {
-    const id = accountId ?? currentUser.value?.id;
+    const id = accountId ?? user.value?.accountId;
     if (id === void 0 || id === "") {
       throw new Error("No account ID available");
     }
     await api.revokeAllSessions(id);
   }
   return {
-    // State
-    currentUser,
+    // Primary State (use this!)
+    user,
+    // Full account info (for advanced use cases)
+    accountInfo,
     // Getters
     getFullName,
     getIsLoggedIn,
     getEmail,
+    getRoles,
+    getAccountType,
+    isPersonAccount,
+    isEntityAccount,
     // Authentication Actions
     login,
     logout,
@@ -481,5 +531,6 @@ function useAuth() {
 
 exports.AuthApi = AuthApi;
 exports.AuthState = AuthState;
+exports.accountToUser = accountToUser;
 exports.initAuth = initAuth;
 exports.useAuth = useAuth;